Chatwoot

Qué hace esta integración

Cuando un contacto escribe por WhatsApp, widget web u otro canal conectado a Chatwoot, Chatwoot avisa a EasyChatBot. Tu bot procesa el mensaje con el mismo motor que el widget web — contexto, intenciones e historial — y la respuesta vuelve a Chatwoot para que el contacto la vea en su canal.

Es independiente del widget embebido en tu web, de Rocket.Chat Omnichannel y de la API con clave: puedes usar varias integraciones a la vez si lo necesitas.

Importante: las respuestas de agentes humanos se gestionan desde Chatwoot, no desde el panel de EasyChatBot. En EasyChatBot verás el historial completo en modo lectura.

sequenceDiagram
    participant Contacto
    participant CW as Chatwoot
    participant ECB as EasyChatBot
    participant Panel as Tu_panel

    Contacto->>CW: Escribe por WhatsApp o widget
    CW->>ECB: Notifica nuevo mensaje
    ECB->>ECB: Genera respuesta con IA
    ECB->>CW: Envía respuesta del bot
    ECB->>Panel: Actualiza conversación en tiempo real

Antes de empezar

• Plan Eter Plus.
• Bot en estado En ejecución (la integración solo funciona en ese estado).
• Acceso de administrador a tu instancia de Chatwoot.
• Un inbox ya creado en Chatwoot (WhatsApp, widget web, email, etc.).
• Un Agent Bot creado en Chatwoot (o listo para crearlo durante la configuración).
• URL base de tu servidor Chatwoot (ejemplo: https://chat.tudominio.com).
• Que Chatwoot pueda llamar por internet a la URL del webhook que te da EasyChatBot (HTTPS en producción).

Nota: por ahora solo los mensajes de texto activan la IA. Adjuntos, tarjetas y plantillas de WhatsApp no generan respuesta automática.

Configuración paso a paso

La configuración se hace en dos sitios: primero recoges datos en EasyChatBot, luego los completas en Chatwoot y vuelves a guardar en EasyChatBot.

Parte A — En EasyChatBot

Ve a Mis Chatbots → tu bot → Código de instalación → sección Chatwoot.

1. Abre el modal Código de instalación y baja hasta la sección Chatwoot.
2. Activa Activar integración Chatwoot.
3. Copia la URL del Webhook (botón copiar). La pegarás en Chatwoot.
4. Rellena URL de tu servidor Chatwoot (ejemplo: https://chat.tudominio.com, sin barra final).
5. Opcional: Account ID — si lo configuras, solo se aceptarán mensajes de esa cuenta de Chatwoot.
6. Deja pendientes API Access Token y Webhook Secret; los obtendrás en Chatwoot en los pasos siguientes.
7. Cuando tengas todos los datos, pulsa Guardar configuración Chatwoot.

Parte B — En Chatwoot

Los menús de Chatwoot están en inglés. Sigue estos pasos:

1. Ve a Settings → Integrations → Webhooks y crea un webhook nuevo.
2. Pega la URL del Webhook que copiaste de EasyChatBot.
3. Marca todos los eventos disponibles (recomendado).
4. Copia el Webhook Secret que te muestra Chatwoot y pégalo en EasyChatBot, en el campo Webhook Secret.
5. Obtén el API Access Token del Agent Bot: ve a Settings → Bots, selecciona tu bot y copia el token. Pégalo en EasyChatBot como API Access Token.
6. Vincula el Agent Bot al inbox (WhatsApp, widget web, etc.) según la documentación de Chatwoot 4.15.
7. Guarda en ambos lados y prueba enviando un mensaje de prueba desde el canal conectado.

Documentación oficial de Chatwoot: How to use webhooks.

Contexto del visitante

En la sub-pestaña General del modal Chatwoot puedes configurar qué datos del contacto de Chatwoot se incluyen en el contexto interno del bot (system prompt). El visitante no ve este bloque; sirve para que la IA personalice el saludo y no vuelva a pedir en charla casual datos que ya conoce.

Qué puedes incluir

• Datos de contacto: nombre, email, teléfono, identificador y ciudad/país (desde atributos adicionales de Chatwoot).
• Etiquetas: etiquetas de la conversación o del contacto en Chatwoot (ej. vip, moroso).
• Atributos personalizados: campos definidos en tu cuenta Chatwoot (empresa, dirección, etc.).
• Notas del contacto: notas del perfil del contacto en Chatwoot (pestaña Notes del contacto).
• Notas de la conversación: notas privadas que los agentes dejan en la conversación (mensajes con private=true).
• Canal: siempre en el JSON como canal (WhatsApp, Telegram, widget web, etc.).

Formato en el system prompt

EasyChatBot inyecta el bloque al inicio del system prompt (no es un tool MCP). Tras el encabezado user_contact: va un JSON plano con los campos del visitante. Los atributos personalizados usan el nombre de la variable de Chatwoot humanizado (ej. direccion_de_casa → direccion de casa en el JSON). Las etiquetas van en etiquetas. Las notas del perfil del contacto en notas_contacto y las notas privadas de la conversación en notas_conversacion (arrays).

Instrucciones editables

En la misma sección puedes editar el texto de Instrucciones que va después del JSON: uno para el chat general y otro para acciones MCP que muestran un subconjunto de user_contact. Si lo dejas vacío al guardar, EasyChatBot usa el texto predeterminado. El botón Restaurar predeterminadas vuelve al texto de fábrica.

Explorar campos en Chatwoot

Con URL del servidor y el Token API de perfil, usa el botón Explorar campos en Chatwoot. El Account ID es opcional: si no lo indicas, EasyChatBot lo obtiene de GET /api/v1/profile con tu token. Si tu usuario tiene varias cuentas Chatwoot, debes indicar el Account ID manualmente.

El token de perfil solo sirve para listar atributos personalizados en el panel de configuración. Las etiquetas del contacto o la conversación se sincronizan por webhook cuando el visitante chatea y no requieren ese token para incluirse en el contexto del bot.

Acciones del bot (citas, formularios, APIs)

El contexto del visitante es orientación para el LLM: si configuras una acción que pide confirmar email o teléfono (cita, request_data, API Connect, etc.), ese flujo de validación sigue activo aunque el dato ya aparezca en el contexto. EasyChatBot no rellena automáticamente los campos de las acciones desde Chatwoot en esta versión.

Agent Bot e inbox

El Agent Bot es la identidad con la que EasyChatBot responde en Chatwoot. Sin él, EasyChatBot no puede enviar mensajes al contacto.

Qué necesitas del Agent Bot

1. En Chatwoot, ve a Settings → Bots y crea un Agent Bot (o usa uno existente).
2. Copia su API Access Token y pégalo en EasyChatBot en el campo API Access Token.
3. Asocia ese Agent Bot al inbox de tu canal (WhatsApp, widget web, etc.).

No mezcles estas claves

Son tres credenciales distintas. Si las intercambias, el bot dejará de responder o verás mensajes duplicados.

WhatsApp

Si conectas WhatsApp a Chatwoot, el flujo es: el contacto escribe en WhatsApp → Chatwoot recibe el mensaje → EasyChatBot responde con IA → la respuesta llega al móvil del contacto.

En EasyChatBot verás origen Chatwoot y el teléfono del contacto en Mis conversaciones (en lugar de la IP del navegador).

Indicador «escribiendo» en WhatsApp (opcional)

El chat funciona sin estos campos; solo sirven para que el contacto vea los tres puntos de «escribiendo» en su móvil mientras el bot piensa.

En EasyChatBot, en la sección Chatwoot, busca el bloque Indicador escribiendo en WhatsApp (opcional):

• Access Token WhatsApp: la misma «Clave de API» del inbox WhatsApp en Chatwoot o Meta Business (empieza por EAA…). No es el Webhook Secret ni el token del Agent Bot.
• Phone Number ID: el ID numérico de tu número de producción en Meta Business → WhatsApp → API Setup. No uses el número de prueba (suele empezar por 555…).

Tras guardar, prueba enviando un mensaje por WhatsApp. Si no ves «escribiendo» en el móvil, revisa la sección Problemas frecuentes.

Telegram

Si conectas Telegram a Chatwoot, el flujo es el mismo: contacto en Telegram → Chatwoot → EasyChatBot responde con IA → la respuesta llega en la app de Telegram.

En Mis conversaciones verás origen Chatwoot y el canal Telegram (no la IP del navegador).

Indicador «escribiendo» en Telegram (opcional)

El chat funciona sin este campo; solo sirve para que el contacto vea «escribiendo…» en Telegram mientras el bot piensa.

En EasyChatBot, pestaña Chatwoot del modal de instalación → sub-pestaña Telegram:

• Bot Token Telegram: el mismo token que obtuviste en BotFather y configuraste en el inbox Telegram de Chatwoot (123456:ABC…). No es el Webhook Secret ni el token del Agent Bot.

Tras guardar, envía un mensaje de prueba por Telegram. Si no ves «escribiendo», revisa que el token coincida con el del inbox y la sección Problemas frecuentes.

Notas de voz en Telegram (opcional)

Con el toggle Recibir notas de voz activo en la configuración del bot (plan Eter Plus) y un modelo STT compatible, las notas de voz que envíe el contacto por Telegram se transcriben y el bot responde como si fuera texto. Usa el mismo toggle que para WhatsApp.

Opcionalmente puedes activar Mostrar transcripción en el chat (segundo toggle, desactivado por defecto): si está activo, tras transcribir la nota el bot envía al visitante en WhatsApp/Telegram un mensaje con la transcripción (idealmente como respuesta a la nota de voz) antes de la respuesta normal del bot. En el panel EasyChatBot verás ese envío con el badge «Transcripción enviada al visitante».

Web widget (Chatwoot vs EasyChatBot)

Puedes elegir uno de tres modos para tu sitio web. Los tres usan el mismo motor de IA; la interfaz, el canal y la gestión humana difieren.

Widget ECB con backend Chatwoot (inbox Website)

Mantiene la interfaz del widget EasyChatBot pero envía los mensajes del visitante al inbox Website de Chatwoot. La IA responde por streaming SSE en el widget ECB; las respuestas se replican a la bandeja Chatwoot. Los agentes humanos responden desde Chatwoot y sus mensajes llegan al visitante por WebSocket ECB.

1. Activa la integración en Mis Chatbots → Código de instalación → Chatwoot → General (webhook, Agent Bot, credenciales).
2. En Chatwoot, crea o usa un inbox Website y vincula el Agent Bot.
3. Copia el Website Token en EasyChatBot → Chatwoot → Web widget.
4. Activa el toggle Enviar conversaciones del widget ECB por Chatwoot en la misma sub-pestaña.
5. Embebe easychatbot.js con data-botid (pestaña Widget) en tu sitio — no pegues el snippet del SDK de Chatwoot.

Requisitos operativos: plan Eter Plus, cw_enabled, cw_server_url y Website Token configurados. No requiere iframe de Chatwoot ni ajustes de X-Frame-Options en Nginx (solo aplica al widget nativo CW).

Instalar el widget de Chatwoot (nativo)

1. Activa la integración en Mis Chatbots → Código de instalación → Chatwoot → General (webhook, Agent Bot, credenciales).
2. En Chatwoot, crea un inbox Website (Settings → Inboxes → Add inbox → Website).
3. Vincula el Agent Bot a ese inbox.
4. Copia el Website Token del inbox y pégalo en EasyChatBot → Chatwoot → Web widget.
5. Copia el snippet generado y pégalo antes de </body> en tu web (en lugar del embed EasyChatBot en esa página).

WhatsApp, Telegram y el widget web de Chatwoot comparten la misma integración (mismo webhook y Agent Bot). Solo cambia el inbox/canal en Chatwoot.

Uso diario

Mis conversaciones

• Badge Chatwoot en el tipo de conversación.
• Estados: Activa (el bot responde), Control humano (un agente atiende) o Terminada.
• Historial completo: mensajes del contacto, respuestas del bot, agentes humanos y avisos del sistema.
• Botón Abrir en Chatwoot para responder o asignar agentes desde Chatwoot.
• El panel de EasyChatBot es solo lectura para conversaciones Chatwoot: no puedes escribir respuestas ni tomar/liberar control desde aquí.

Cuándo responde el bot y cuándo un humano

Notificaciones: las solicitudes de handoff y los avisos durante control manual no generan tarjeta en Notificaciones de EasyChatBot. Gestiónalas directamente en Chatwoot.

Indicador «escribiendo»

Mientras el bot genera una respuesta, puedes ver el indicador de escritura (tres puntos) en distintos sitios:

En el panel de EasyChatBot, el mensaje del contacto aparece antes de los tres puntos mientras el bot procesa la respuesta.

En WhatsApp y Telegram, el indicador desaparece al enviar la respuesta del bot o tras unos segundos si tarda mucho.

Problemas frecuentes

• El bot no responde: comprueba que el bot esté En ejecución, que Activar integración Chatwoot esté activo, que hayas pulsado Guardar configuración Chatwoot con el API Access Token y el Webhook Secret correctos, y prueba enviando un mensaje de prueba desde Chatwoot.
• No responde nada / error del servidor: si tu equipo administra el servidor de EasyChatBot, pídeles que comprueben que el servicio de chat está en marcha. Mientras esté caído, ningún canal (widget, Chatwoot, WhatsApp) recibirá respuestas.
• Respuestas duplicadas: revisa que el Webhook Secret y el API Access Token del Agent Bot sean los correctos y no estén intercambiados.
• Token incorrecto: el Webhook Secret sale del webhook en Chatwoot; el API Access Token sale del Agent Bot en Settings → Bots. No uses uno en lugar del otro.
• No hay «escribiendo» en WhatsApp: usa el Phone Number ID de tu número real en Meta Business (no el de prueba 555…) y la misma «Clave de API» del inbox WhatsApp. Guarda de nuevo en EasyChatBot.
• No hay «escribiendo» en Telegram: en la sub-pestaña Telegram del modal Chatwoot, guarda el Bot Token exacto de BotFather (mismo que en el inbox Telegram de Chatwoot).
• Nota de voz Telegram sin respuesta: activa Recibir notas de voz en la configuración del bot, plan Eter Plus y modelo STT con soporte de audio.
• No se ven los tres puntos en el panel EasyChatBot: mantén abierta la conversación en el panel mientras pruebas; el indicador solo se actualiza en tiempo real en esa vista.
• Versión antigua de Chatwoot: actualiza a 4.16.0 (o al menos 4.15.1) y vuelve a vincular el Agent Bot al inbox.
• Solo texto: mensajes con imágenes, archivos o plantillas de WhatsApp no activan la IA por ahora. Las notas de voz en WhatsApp y Telegram sí, con el toggle STT y plan Eter Plus.

Si sigues con dudas, prueba primero con un canal de prueba (pocos contactos) y revisa en Mis conversaciones que los mensajes lleguen con origen Chatwoot.