Configura herramientas personalizadas para Captain

Descubrir

Las herramientas personalizadas permiten que el asistente llame a tus propios sistemas durante una conversación, por ejemplo para verificar un pedido, una garantía o una reserva, en lugar de transferir la conversación.

Plan y acceso: Business o Enterprise ([Enlace: Precios y Planes]). En Startups, Herramientas usualmente muestra Actualizar para usar herramientas con Captain. Cada asistente tiene su propia lista de herramientas. Los administradores crean herramientas, y solo los administradores pueden ver las credenciales guardadas. Autoalojado: el Super Admin activa Herramientas Personalizadas para la cuenta.

Configuración y prueba

Antes de empezar

• Un endpoint HTTPS en un nombre de host público. Chatwoot bloquea HTTP sin cifrar, direcciones IP, localhost, redes privadas y direcciones .local.

• El endpoint debe aceptar la conexión en 2 segundos y responder en 20 segundos, con una respuesta de 1 MB o menos.

• Sus credenciales, si las necesita.

Crear una herramienta

1. Ve a Captain > Herramientas y haz clic en Crear una nueva herramienta. Primero usa el selector de asistentes en la parte superior para elegir el asistente para el que es la herramienta. El formulario se abre en un panel lateral.

   

2. Completa lo siguiente:

   • Nombre de la herramienta: corto, por ejemplo "Consulta de pedidos" (55 caracteres o menos).

   • Descripción: cuándo debe usarla el asistente, escrita como un informe para un agente nuevo. Esto determina si el asistente elige la herramienta.

   • Método: GET para leer datos; POST, PUT o PATCH para enviar o modificar datos; DELETE para eliminar algo.

   • URL del endpoint: usa {{ parameter_name }} para valores que el asistente completará, por ejemplo https://api.example.com/orders/{{ order_id }}.

   • Tipo de autenticación: Ninguno, Bearer Token, Basic Auth o API Key (con Nombre del header y Valor del header). Usa esto para las credenciales.

   • Headers: haz clic en Agregar header para headers fijos que tu API necesite en cada llamada, como una versión de la API o ID de inquilino (hasta 16). Los valores se envían exactamente como los escribas. Chatwoot establece Authorization, Host, Content-Length, Content-Type y cualquier header que empiece por X-Chatwoot, así que no puedes agregar esos.

   • Parámetros: haz clic en Agregar parámetro para cada valor que el asistente debe obtener del cliente. Da un nombre, tipo, descripción y marca Obligatorio si es necesario.

   • Plantilla de cuerpo de la solicitud (Opcional): para POST, PUT o PATCH. Esta y la plantilla de respuesta están en Plantillas. La plantilla de solicitud es un cuerpo JSON. Soporta Liquid, por ejemplo {{ order_id }} para un parámetro.

   • Plantilla de respuesta (Opcional): selecciona los campos que necesita el asistente, por ejemplo Pedido {{ response.order_id }} estado: {{ response.status }}. Lee la respuesta del API a través de response, por ejemplo {{ response.status }}. Deja la plantilla en blanco para enviar a Captain el JSON crudo.

     

   

3. Haz clic en Probar conexión, luego en Crear.

   

Probar conexión solo funciona para endpoints sin plantillas ni cuerpo de solicitud. Para los demás, prueba en el Playground. Un resultado verde significa que tu endpoint devolvió un estado 2xx: es accesible y aceptó las credenciales.

Prueba

Haz una pregunta en el Playground que requiera la herramienta, por ejemplo "¿Dónde está el pedido 1234?". Verifica que la respuesta use datos reales.

Obtén valor

• Las herramientas personalizadas funcionan mejor para búsquedas con entradas claras, como un estado de pedido, una reserva o un registro por ID.

• Cada asistente puede tener hasta 50 herramientas. Mantén la lista corta igualmente: con muchas herramientas el asistente es más propenso a elegir la equivocada.

• Agregar, editar, desactivar o eliminar una herramienta solo la cambia para el asistente que estás viendo. Las herramientas que existían antes de que fueran por asistente fueron copiadas a cada asistente, así que revisa cada uno.

• ¿Manejas varios asistentes? Da a cada uno solo las herramientas que necesita.

• Desactiva una herramienta con su interruptor en vez de eliminarla. Si un escenario la usa, Chatwoot te advertirá primero. Ver Límites, pautas y escenarios.

• Chatwoot envía headers con cada llamada para que tu sistema sepa la cuenta, conversación, correo y teléfono de contacto, asistente y si el contacto está verificado. Para datos privados, revisa el header X-Chatwoot-Contact-Inbox-Verified antes de responder. Sin validación de identidad, un visitante puede escribir cualquier email en el widget. Las herramientas que solo devuelven datos públicos no necesitan esta verificación. Ver [Enlace: Validación de identidad].

• Si tu API devuelve texto escrito por los clientes, devuelve solo los campos estructurados que necesitas. Captain lee la respuesta tal cual, así que texto libre podría contener instrucciones que podría seguir.

Solución de problemas

Más causas: Solución de problemas de Captain.