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**. \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ1FZM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cb577b7e950815be109f2925cac60ce4b25305ac/CleanShot%202026-04-01%20at%2015.53.06@2x.png) 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. \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRDQ4M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--dc19f2d14e08901f6921007175ffd5399064a947/CleanShot%202026-04-01%20at%2016.52.41@2x.png) \ **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. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREk5M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8a952a29edf820a845a1a3ca27072386c225eeef/image.png) 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 `.local` está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 }}` | \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--243c121ad98c746cdbfb6aae317471cc2485ccad/CleanShot%202026-04-01%20at%2015.59.39@2x.png) ### 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 %}` | \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2a8aaa32f6747f6cdfca6d3abcac3b62bce5060f/image.png) 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.