Las Herramientas Personalizadas permiten que Captain llame a tus APIs externas durante las conversaciones, para que pueda comprobar el estado del sistema, buscar horarios o recuperar datos de tus propios servicios sin pasar 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 contestación.
Las Herramientas Personalizadas están disponibles en el plan Business y superiores.
Crear una herramienta
Navega a Captain -> Tools y haz clic en Crear una nueva herramienta.
Completa los siguientes campos:
Nombre de la herramienta — Un nombre corto como "Estado del sistema" o "Búsqueda de horarios" (máx. 55 caracteres).
Descripción — Indica a Captain cuándo debe usar esta herramienta. Este es el campo más importante. Escríbelo como si estuvieras informando a un agente de soporte: “Comprueba el estado actual del sistema, incluyendo incidentes o mantenimientos en curso.” Descripciones vagas como “API de estado” harán que Captain pierda oportunidades de usar la herramienta.
Método — Elige GET (para obtener datos) o POST (para enviar datos).
URL del Endpoint — La URL de tu API. Utiliza {{ 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.
Autenticación — Elige cómo tu API autentica las solicitudes:
| Tipo | Lo que proporcionas |
|------|---------------------|
| Ninguna | Sin autenticación |
| Bearer Token | Una cadena de token |
| Basic Auth | Nombre de usuario y contraseña |
| API Key | Un nombre de encabezado personalizado y valor |
Las credenciales de autenticación solo son visibles para los administradores de la cuenta.
Parámetros — Define lo que Captain debe extraer del mensaje del cliente. Cada parámetro necesita un nombre, tipo y descripción. Por ejemplo: query (String) — "El título de la película o fecha sobre la que pregunta el cliente."
Plantilla de solicitud (solo POST) — Una plantilla JSON usando sintaxis Liquid:
{ "query": "{{ query }}", "source": "captain" }
Plantilla de respuesta — 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 campos relevantes:
Estado del sistema: {{ response.status }}. {{ response.message }}
Utiliza response para acceder al cuerpo JSON analizado. Las plantillas de respuesta ayudan a Captain a centrarse en los datos relevantes y evitan campos internos como IDs de bases de datos o información de depuración.
Probar tu herramienta
Haz clic en Probar conexión antes de guardar para verificar que tu endpoint es accesible. La prueba informa el código de estado HTTP.
Un resultado verde (HTTP 200–299) significa que la conexión y 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, revisa lo siguiente:
-
401 No autorizado — Tus credenciales de autenticación son incorrectas. Verifica tu bearer token, API key o nombre de usuario/contraseña.
-
403 Prohibido — Tu API está rechazando la solicitud. Si requieres verificación de identidad, ten en cuenta que las solicitudes de prueba no incluyen encabezados de contacto.
-
404 No encontrado — La URL del endpoint es incorrecta. Verifica la ruta y asegúrate de que tu API esté en funcionamiento.
-
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 intervalo.
Contexto enviado con cada llamada de herramienta
Cuando Captain llama a tu API, incluye encabezados de metadatos para que tu backend sepa el contexto:
| Encabezado | Descripción |
|--------|-------------|
| X-Chatwoot-Account-Id | El ID de tu cuenta |
| X-Chatwoot-Conversation-Id | El ID de la conversación |
| X-Chatwoot-Contact-Email | El email del cliente (si está disponible) |
| X-Chatwoot-Contact-Inbox-Verified | Si la identidad del cliente está verificada por HMAC |
Encabezados 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 estos encabezados para buscar al cliente en tu propio sistema, registrar qué conversaciones activaron llamadas a la API y verificar la autenticidad de las solicitudes.
Seguridad
Protecciones integradas:
-
Todos los endpoints deben usar HTTPS
-
Las solicitudes a rangos de IP privadas, localhost y dominios
.localestán bloqueadas -
No se siguen redirecciones HTTP
-
Las respuestas están limitadas a 1 MB
-
Las credenciales de autenticación solo son visibles para administradores
Verificación de identidad: Si tu herramienta devuelve datos específicos del cliente (órdenes, facturación, detalles de cuenta), tu API debe comprobar el encabezado X-Chatwoot-Contact-Inbox-Verified. Sin la verificación HMAC activada en tu bandeja de entrada, un visitante podría establecer cualquier correo electrónico en el widget de chat. Solo devuelve datos sensibles cuando este encabezado 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 el usuario (reseñas, publicaciones en foros), un texto malicioso podría influir en el comportamiento de Captain. Usa plantillas de respuesta para extraer solo campos estructurados y sanitiza el contenido de tu lado de API.
Límites
| Límite | Valor |
|-------|-------|
| Máx. 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 | Máx. 1 MB |
| Tiempo de espera de la solicitud | 30 segundos |
Cuándo usar herramientas personalizadas
Las herramientas personalizadas son más adecuadas para búsquedas estructuradas con entradas predecibles: comprobar el estado del sistema, obtener horarios o buscar registros por ID. Si ya tienes una integración dedicada de Chatwoot para tu caso de uso (por ejemplo, Shopify para e-commerce), usa esa en su lugar: las integraciones dedicadas manejan la búsqueda, la coincidencia difusa y la sincronización de datos de manera más fiable que una sola llamada API.
Ejemplos
Comprobación de estado del sistema
Una herramienta sencilla sin parámetros: Captain la llama cuando un cliente pregunta si algo está caído.
| Campo | Valor |
|-------|-------|
| Nombre de la herramienta | Estado del sistema |
| Descripción | Comprueba el estado operativo actual del sistema, incluidos incidentes en curso o mantenimientos programados. Usa cuando un cliente reporte problemas o pregunte si el sistema está caído. |
| Método | GET |
| URL del endpoint | https://status.yourcompany.com/api/v1/status |
| Autenticación | Ninguna |
| Parámetros | (ninguno) |
| Plantilla de respuesta | Estado del sistema: {{ response.status }}. {{ response.message }} |
Búsqueda de horarios / cartelera
Para negocios con horarios, calendarios o listas de eventos: los clientes preguntan qué está disponible y Captain obtiene el horario actual.
| Campo | Valor |
|-------|-------|
| Nombre de la herramienta | Búsqueda de horarios |
| Descripción | Busca los horarios de películas y funciones. Utiliza cuando un cliente pregunta qué películas están en cartelera o cuándo se proyecta una película específica. |
| Método | GET |
| URL del endpoint | https://api.yourcinema.com/v1/showtimes?q={{ query }} |
| Autenticación | Bearer Token |
| Parámetros | query (String, obligatorio) — "El título de la película o la fecha de la proyección por la que pregunta el cliente" |
| Plantilla de respuesta | {% for show in response.showtimes %}{{ show.title }} — {{ show.date }} a las {{ show.time }}{% endfor %} |
Las Herramientas Personalizadas funcionan mejor cuando las entradas son directas y la respuesta de la API es predecible: comprobaciones de estado, búsquedas y otras consultas estructuradas son el caso ideal.