Configura herramientas personalizadas para el Capitán

Descubre

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

Planificación y acceso: Business o Enterprise (Precios y planes). En Startups, Tools suele mostrar Upgrade to use tools with Captain. Cada asistente tiene su propia lista de herramientas. Los administradores crean herramientas, y solo los administradores pueden ver las credenciales guardadas. Self-hosted: el Super Admin activa Custom Tools para la cuenta.

Configura y prueba

Antes de empezar

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

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

• Sus credenciales, si las necesita.

Crear una herramienta

1. Ve a Captain > Tools y haz clic en Create a new tool. Primero utiliza el selector de asistente en la parte superior para elegir el asistente para el que será la herramienta. El formulario se abre en un panel lateral.

   

2. Completa:

   • Tool Name: corto, por ejemplo "Consulta de pedido" (55 caracteres o menos).

   • Description: cuándo debe utilizarlo el asistente, escrito como un briefing para un nuevo agente. Esto decide si el asistente elige la herramienta.

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

   • Endpoint URL: usa {{ parameter_name }} para los valores que completa el asistente, por ejemplo https://api.example.com/orders/``{{ order_id }}.

   • Authentication Type: None, Bearer Token, Basic Auth o API Key (con Header Name y Header Value). Utiliza esto para las credenciales.

   • Headers: haz clic en Add Header para encabezados fijos que tu API requiera en cada llamada, como una versión de API o ID de tenant (hasta 16). Los valores se envían exactamente como se escriben. Chatwoot establece Authorization, Host, Content-Length, Content-Type y cualquier encabezado que comience con X-Chatwoot por sí mismo, así que no puedes añadir esos.

   • Parameters: haz clic en Add Parameter para cada valor que el asistente deba obtener del cliente. Da un nombre, tipo, descripción y marca Required si es necesario.

   • Request Body Template (Optional): para POST, PUT o PATCH. Esta plantilla y la plantilla de respuesta están bajo Templates. La plantilla de solicitud es un cuerpo JSON. Soporta Liquid, por ejemplo {{ order_id }} para un parámetro.

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

     

   

3. Haz clic en Test connection y luego en Create.

   

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

Pruébalo

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.

Saca el máximo valor

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

• Cada asistente puede tener hasta 50 herramientas. Mantén la lista corta de todas formas: con muchas herramientas, es más probable que el asistente elija la incorrecta.

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

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

• Desactiva una herramienta con su interruptor en lugar de eliminarla. Si un escenario la usa, Chatwoot te avisará primero. Consulta Define las reglas, directrices y escenarios de Captain.

• Chatwoot envía encabezados en cada llamada para que tu sistema sepa la cuenta, conversación, correo electrónico de contacto y teléfono, asistente y si el contacto está verificado. Para datos privados, verifica el encabezado X-Chatwoot-Contact-Inbox-Verified antes de responder. Sin validación de identidad, un visitante puede escribir cualquier correo en el widget. Las herramientas que devuelven solo datos públicos no necesitan esta verificación. Consulta ¿Cómo habilitar la validación de identidad en Chatwoot?.

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

Solución de problemas

Más causas: Soluciona problemas de Captain.