Las Herramientas Personalizadas permiten que Captain llame a tus APIs externas durante las conversaciones, de modo que pueda consultar el estado del sistema, buscar horarios o recuperar datos de tus propios servicios sin derivar a un agente humano.
Cuando un cliente hace una pregunta, Captain extrae los valores relevantes de la conversación, los inserta en tu solicitud API y utiliza la respuesta para formar su respuesta.
Herramientas Personalizadas está disponible en el plan Business y superiores.
Creando una herramienta
Navega a Captain -> Tools y haz clic en Create a new tool.
Completa los siguientes campos:
Tool Name — Un nombre corto como "Estado del Sistema" o "Consulta de Horarios" (máximo 55 caracteres).
Description — Indica a Captain cuándo debe usar esta herramienta. Este es el campo más importante. Escríbelo como si informaras a un agente de soporte: "Consulta el estado actual del sistema, incluidos cualquier incidente en curso o mantenimiento." Descripciones vagas como "API de Estado" harán que Captain pierda oportunidades de utilizar la herramienta.
Method — Elige GET (para obtener datos) o POST (para enviar datos).
Endpoint URL — La URL de tu API. Usa {{ parameter_name }} para insertar valores extraídos de la conversación:
https://api.yourcompany.com/v1/showtimes?q={{ query }}
La URL debe usar HTTPS, debe ser un nombre de host (no una dirección IP) y no puede apuntar a localhost o redes privadas.
Authentication — Elige cómo tu API autentica las solicitudes:
| Tipo | Qué proporcionas |
|------|------------------|
| None | Sin autenticación |
| Bearer Token | Una cadena de token |
| Basic Auth | Nombre de usuario y contraseña |
| API Key | Un nombre de cabecera personalizado y su valor |
Las credenciales de autenticación solo están visibles para los administradores de la cuenta.
Parameters — Define qué debe extraer Captain del mensaje del cliente. Cada parámetro requiere un nombre, tipo y descripción. Por ejemplo: query (String) — "El título de la película o la fecha que el cliente está consultando."
Request Template (solo POST) — Una plantilla de cuerpo JSON usando sintaxis Liquid:
{ "query": "{{ query }}", "source": "captain" }
Response Template — Controla lo que Captain ve de la respuesta de tu API. Si se deja en blanco, Captain recibe el JSON sin procesar. Usa Liquid para extraer los campos relevantes:
Estado del sistema: {{ response.status }}. {{ response.message }}
Usa response para acceder al cuerpo JSON analizado. Las plantillas de respuesta ayudan a Captain a centrarse en los datos relevantes y evitar campos internos como IDs de base de datos o información de depuración.
Probando tu herramienta
Haz clic en Test connection antes de guardar para verificar que tu endpoint sea accesible. La prueba informa el código de estado HTTP.
Un resultado verde (HTTP 200–299) significa que la conexión y la autenticación funcionan. Ten en cuenta que la prueba envía la URL sin completar los valores de los parámetros, por lo que solo verifica que tu endpoint sea accesible y que tus credenciales sean aceptadas.
Si la prueba falla, verifica lo siguiente:
-
401 Unauthorised — Tus credenciales de autenticación son incorrectas. Verifica tu token bearer, API key o nombre de usuario/contraseña.
-
403 Forbidden — Tu API está rechazando la solicitud. Si requieres verificación de identidad, ten en cuenta que las pruebas no incluyen cabeceras de contacto.
-
404 Not Found — La URL del endpoint es incorrecta. Verifica la ruta y asegúrate de que tu API esté funcionando.
-
Timeout — Tu API tardó demasiado en responder. Las herramientas personalizadas tienen un tiempo de espera de 30 segundos; asegúrate de que tu endpoint responda dentro de ese plazo.
Contexto enviado con cada llamada a la herramienta
Cuando Captain llama a tu API, incluye cabeceras de metadatos para que tu backend sepa el contexto:
| Cabecera | Descripción |
|----------|-------------|
| X-Chatwoot-Account-Id | ID de tu cuenta |
| X-Chatwoot-Conversation-Id | El ID de la conversación |
| X-Chatwoot-Contact-Email | El correo electrónico del cliente (si está disponible) |
| X-Chatwoot-Contact-Inbox-Verified | Si la identidad del cliente está verificada por HMAC |
Cabeceras adicionales incluyen X-Chatwoot-Assistant-Id, X-Chatwoot-Tool-Slug, X-Chatwoot-Contact-Id, X-Chatwoot-Contact-Phone y X-Chatwoot-Conversation-Display-Id.
Puedes usar estas cabeceras para buscar al cliente en tu propio sistema, registrar qué conversaciones dispararon llamadas a la API y verificar la autenticidad de la solicitud.
Seguridad
Protecciones incorporadas:
-
Todos los endpoints deben usar HTTPS
-
Las solicitudes a rangos de IP privadas, localhost y dominios
.localestán bloqueadas -
Las redirecciones HTTP no son seguidas
-
Las respuestas se limitan a 1 MB
-
Las credenciales de autenticación solo están visibles para administradores
Verificación de identidad: Si tu herramienta devuelve datos específicos del cliente (pedidos, facturación, detalles de cuenta), tu API debe revisar la cabecera X-Chatwoot-Contact-Inbox-Verified. Sin la verificación HMAC habilitada en tu inbox, un visitante podría establecer cualquier correo electrónico en el widget de chat. Solo devuelve datos sensibles cuando esta cabecera sea true. Para herramientas que devuelven datos públicos (horarios, estado del sistema), esta comprobación no es necesaria.
Inyección de prompts: Si tu API devuelve contenido generado por usuarios (comentarios, publicaciones de foros), texto malicioso podría influir en el comportamiento de Captain. Usa plantillas de respuesta para extraer solo campos estructurados y sanitiza el contenido en tu lado de la API.
Límites
| Límite | Valor |
|--------|-------|
| Máximo de herramientas por cuenta | 15 |
| Recomendado | 10 o menos (aparece una advertencia por encima de 10) |
| Longitud del nombre de la herramienta | 55 caracteres |
| Tamaño de la respuesta | 1 MB máximo |
| Tiempo de espera de la solicitud | 30 segundos |
Cuándo usar herramientas personalizadas
Las herramientas personalizadas son ideales para búsquedas estructuradas con entradas predecibles — consultar estado del sistema, recuperar horarios o buscar registros por ID. Si ya tienes una integración dedicada de Chatwoot para tu caso (por ejemplo, Shopify para e-commerce), utiliza esa en su lugar — las integraciones dedicadas gestionan la búsqueda, la coincidencia aproximada y la sincronización de datos de forma más fiable que una sola llamada API.
Ejemplos
Verificación de Estado del Sistema
Una herramienta simple sin parámetros — Captain la llama cuando un cliente pregunta si algo está caído.
| Campo | Valor |
|-------|-------|
| Tool Name | Estado del Sistema |
| Description | Consulta el estado actual de operación del sistema, incluidos cualquier incidente en curso o mantenimiento planificado. Usar cuando un cliente reporte problemas o pregunte si el sistema está caído. |
| Method | GET |
| Endpoint URL | https://status.yourcompany.com/api/v1/status |
| Auth | None |
| Parameters | (ninguno) |
| Response Template | Estado del sistema: {{ response.status }}. {{ response.message }} |
Consulta de Horarios / Funciones
Para negocios con horarios, tablas de tiempo o listados de eventos — los clientes preguntan qué hay disponible y Captain obtiene el horario actual.
| Campo | Valor |
|-------|-------|
| Tool Name | Consulta de Funciones |
| Description | Consulta los horarios de funciones y programaciones de proyecciones. Usar cuando un cliente pregunte qué películas están en cartelera o cuándo se muestra una película específica. |
| Method | GET |
| Endpoint URL | https://api.yourcinema.com/v1/showtimes?q={{ query }} |
| Auth | Bearer Token |
| Parameters | query (String, requerido) — "El título de la película o la fecha de proyección que pregunta el cliente" |
| Response Template | {% for show in response.showtimes %}{{ show.title }} — {{ show.date }} at {{ show.time }}{% endfor %} |
Las Herramientas Personalizadas funcionan mejor cuando las entradas son directas y la respuesta de la API es predecible — verificaciones de estado, consultas y otras búsquedas estructuradas son ideales para este tipo de herramientas.