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 consultar un pedido, una garantía o una reserva, en lugar de transferir la conversación.

Plan 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 las herramientas y solo ellos pueden ver las credenciales guardadas. En instalaciones autohospedadas: el Super Admin activa Custom Tools para la cuenta.

Configurar y probar

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 un plazo de 2 segundos y responder en un máximo de 20 segundos, con una respuesta de 1 MB o menos.

• Sus credenciales, si las necesita.

Crear una herramienta

1. Ve a Captain > Tools y haz clic en Create a new tool. Primero, usa el selector de asistentes de la parte superior para elegir para qué asistente es la herramienta. El formulario se abre en un panel lateral.

   

2. Completa lo siguiente:

   • Tool Name: breve, por ejemplo, "Consulta de pedidos" (55 caracteres como máximo).

   • Description: cuándo debe usarla el asistente, redactado como instrucciones para un agente nuevo. Esto determina 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 el asistente completa, 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). Usa esta opción para las credenciales.

   • Headers: haz clic en Add Header para agregar los encabezados fijos que tu API necesita en cada llamada, como una versión de API o un ID de inquilino (hasta 16). Los valores se envían exactamente como se escriben. Chatwoot establece por sí mismo Authorization, Host, Content-Length, Content-Type y cualquier encabezado que empiece por X-Chatwoot, por lo que no puedes agregarlos.

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

   • Add verified email: agrega un parámetro. Chatwoot asigna a este parámetro el correo electrónico que el cliente verificó con un código de un solo uso. En las conversaciones con clientes, Captain no puede verlo ni cambiarlo. Usa este parámetro cuando tu API busque al cliente por correo electrónico, por ejemplo, https://api.example.com/orders?email={{ email }}. Una herramienta puede tener un parámetro de correo electrónico verificado.

   • Require email verification: Captain solo puede usar la herramienta después de que el cliente verifique su correo electrónico con un código de un solo uso. Si la herramienta tiene un parámetro de correo electrónico verificado, esta opción siempre está activada.

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

   • Response Template (Optional): selecciona los campos que necesita el asistente, por ejemplo, Estado del pedido {{ response.order_id }}: {{ response.status }}. Lee la respuesta de la API mediante response, por ejemplo, {{ response.status }}. Deja la plantilla en blanco para enviar el JSON sin procesar a Captain.

     

   

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

   

Test connection solo funciona con endpoints sin plantillas ni cuerpo de solicitud. Para los demás, prueba en Playground. Un resultado verde significa que tu endpoint devolvió un estado 2xx: se puede acceder a él y aceptó las credenciales.

Probarla

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

Proteger los datos de los clientes

Un cliente puede escribir cualquier correo electrónico en el widget o en el formulario previo al chat. Algunas herramientas devuelven o modifican los datos de un cliente, como pedidos, facturas o reservas. Activa la verificación del correo electrónico para estas herramientas.

Cuando Captain llama a una de estas herramientas, le pide su correo electrónico al cliente. Chatwoot envía un código de 6 dígitos a esa dirección y el cliente lo escribe en la conversación. La herramienta solo se ejecuta después de que Chatwoot comprueba que el código es correcto.

• La verificación se aplica a una sola conversación. Dura hasta 1 hora, o hasta 3 horas en conversaciones por correo electrónico. Una conversación nueva empieza sin verificación.

• El código caduca después de 30 minutos. El cliente puede probar un código 5 veces. Chatwoot envía un máximo de 5 códigos al cliente en una hora.

• Require email verification no determina a qué correo electrónico envía la herramienta. Si tu API obtiene el correo de un parámetro normal, Captain puede enviar cualquier dirección. Para que la herramienta envíe solo el correo verificado, usa Add verified email.

• Chatwoot puede detectar indicios de que una herramienta usa datos de clientes. Si los detecta y la herramienta no tiene verificación de correo electrónico, Chatwoot muestra Save without email verification? antes de guardar. Haz clic en Go back o Save anyway.

• En Playground y en las sugerencias de respuesta, el usuario es un miembro del equipo. Captain completa el parámetro de correo electrónico verificado. El resultado te indica si Chatwoot verificó esa dirección.

• En los conjuntos de herramientas instalados, los administradores pueden activar o desactivar Require email verification.

Obtener valor

• Las herramientas personalizadas funcionan mejor para consultas con datos de entrada claros, como el estado de un pedido, una reserva o un registro por ID.

• Cada asistente puede tener hasta 50 herramientas. De todos modos, mantén una lista breve: cuantas más herramientas haya, más probable será que el asistente elija la equivocada.

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

• ¿Usas varios asistentes? Dale a cada uno solo las herramientas que necesita.

• Desactiva una herramienta con su interruptor en lugar de eliminarla. Si un escenario la utiliza, Chatwoot te avisará primero. Consulta Configurar las barreras de protección, las pautas y los escenarios de Captain.

• Chatwoot envía encabezados con cada solicitud. Estos le indican a tu sistema la cuenta, la conversación, el contacto, el asistente y la bandeja de entrada.

  • X-Chatwoot-Verified-Email contiene el correo electrónico que el cliente verificó con un código de un solo uso. Si el cliente no lo verificó, Chatwoot no envía este encabezado.

  • X-Chatwoot-Contact-Email contiene el correo electrónico del registro del contacto. Cualquiera puede escribir esta dirección. No la uses para devolver datos privados.

  • X-Chatwoot-Contact-Inbox-Verified es true cuando la validación de identidad (HMAC) verificó el contacto. Este encabezado no verifica el correo electrónico.

  Si tu sistema devuelve datos privados, comprueba X-Chatwoot-Verified-Email o activa la verificación del correo electrónico para la herramienta. Consulta ¿Cómo activar 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: Solucionar problemas de Captain.