Chatwoot
es
Idioma
en English pt_BR Portuguese (Brazil) es Spanish

¿Cómo configurar herramientas personalizadas para Captain?

Open in
View as Markdown Open in ChatGPT Open in Claude
Sojan

Sojan

Última actualización el Jul 17, 2026

Las Herramientas Personalizadas permiten que Captain llame a tus APIs externas durante las conversaciones, para que pueda verificar el estado de garantía, comprobar la cobertura de servicios o extraer datos de tus propios servicios sin necesidad de transferir la conversación 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 elaborar su respuesta.

Las Herramientas Personalizadas están disponibles 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 "Consulta de Garantía" o "Verificación de Zona de Servicio" (máx. 55 caracteres).

Description — Indícale a Captain cuándo debe usar esta herramienta. Este es el campo más importante. Escríbelo como si estuvieras dando instrucciones a un agente de soporte: "Verifica el estado de la garantía de un producto por su número de serie." Descripciones vagas como "API de Garantía" harán que Captain pierda oportunidades de utilizar la herramienta.

Method — Elige GET (para extraer 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/warranty/{{ serial_number }}

La URL debe usar HTTPS, debe ser un nombre de dominio (no una dirección IP), y no puede apuntar a localhost o redes privadas.

Authentication — Elige cómo tu API autentica las solicitudes:

  • None — Sin autenticación

  • Bearer Token — Envía tu token en el encabezado Authorization

  • Basic Auth — Envía un nombre de usuario y contraseña

  • API Key — Envía un nombre y valor de encabezado personalizados (por ejemplo, X-API-Key)

Las credenciales de autenticación solo son visibles para los administradores de la cuenta.


Parameters — Define qué debe extraer Captain del mensaje del cliente. Cada parámetro necesita un nombre, tipo y descripción. Por ejemplo: serial_number (String) — "El número de serie del producto, que se encuentra en la parte posterior del dispositivo."

Request Template (solo POST) — Una plantilla de cuerpo JSON utilizando sintaxis Liquid.

Response Template — Controla lo que Captain ve de la respuesta de tu API. Si se deja en blanco, Captain recibirá el JSON sin procesar.

Usa Liquid para extraer los campos relevantes, por ejemplo: Serie {{ response.serial_number }}: {{ response.warranty_status }}. Expira: {{ response.expiry_date }}.

Usa response para acceder al cuerpo JSON analizado. Las plantillas de respuesta ayudan a Captain a centrarse en los datos relevantes y omitir 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. El test informa el código de estado HTTP.
Un resultado en 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 rellenar 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. Revisa tu token bearer, clave API o usuario/contraseña.

  • 403 Forbidden — Tu API rechaza la solicitud. Si requieres verificación de identidad, ten en cuenta que las pruebas no incluyen encabezados de contacto.

  • 404 Not Found — 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 en ese tiempo.

Contexto enviado con cada llamada a la herramienta

Cuando Captain llama a tu API, incluye encabezados de metadatos para que tu backend sepa el contexto:

  • X-Chatwoot-Account-Id — El 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 ha sido verificada con HMAC

  • X-Chatwoot-Assistant-Id — El asistente de Captain que realiza la llamada

  • X-Chatwoot-Tool-Slug — El identificador interno de la herramienta

  • X-Chatwoot-Contact-Id — El ID de contacto del cliente

  • X-Chatwoot-Contact-Phone — El número de teléfono del cliente (si está disponible)

  • X-Chatwoot-Conversation-Display-Id — El número de visualización de la conversación

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 la solicitud.

Seguridad

Protecciones integradas:

  • 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 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 de clientes (pedidos, facturación, detalles de cuentas), tu API debe comprobar el encabezado 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 este encabezado sea true. Para herramientas que devuelven datos públicos este chequeo no es necesario.

Inyección de prompts: Si tu API retorna contenido generado por usuarios (reseñas, publicaciones de foro), 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

  • Herramientas máximas por cuenta — 15

  • Recomendado — 10 o menos. Aparece una advertencia más allá de 10; más herramientas dificultan que Captain elija la adecuada.

  • 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 consultas estructuradas con entradas predecibles — verificar el estado del sistema, extraer horarios o buscar registros por ID. Si ya tienes una integración dedicada con Chatwoot para tu caso de uso (por ejemplo, Shopify para e-commerce), utiliza esa en su lugar — las integraciones dedicadas gestionan la búsqueda, la coincidencia difusa y la sincronización de datos de forma más fiable que una sola llamada API.

Ejemplos

Consulta de Garantía

Cuando un cliente pregunta si su producto aún está en garantía, Captain puede comprobarlo usando el número de serie.

  • Tool Name: Consulta de Garantía

  • Description: Verifica el estado de la garantía de un producto por su número de serie. Úsalo cuando un cliente pregunte si su producto está cubierto, cuándo expira la garantía o qué tipo de cobertura tiene.

Verificación de Zona de Servicio

Para empresas que operan en regiones específicas — los clientes preguntan si hay servicio disponible en su ubicación.

  • Tool Name: Verificación de Zona de Servicio

  • Description: Verifica si hay servicio o entrega disponible en un área específica usando el código postal o el nombre de la ciudad del cliente.

Las Herramientas Personalizadas funcionan mejor cuando las entradas son sencillas y la respuesta de la API es predecible — verificaciones de estado, consultas y otras búsquedas estructuradas son ideales.