Chatwoot
Conecta WhatsApp, widget web y otros canales de Chatwoot con tu bot: el contacto escribe en Chatwoot, la IA responde automáticamente y todo el historial queda en Mis conversaciones.
Volver al índice de documentación
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).
Usa la versión 4.15.1 de Chatwoot — es la última versión que hemos probado con el Agent Bot vinculado al inbox y con EasyChatBot. Versiones más antiguas pueden dar problemas al asociar el bot al canal o al recibir mensajes.
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.
- Abre el modal Código de instalación y baja hasta la sección Chatwoot.
- Activa Activar integración Chatwoot.
- Copia la URL del Webhook (botón copiar). La pegarás en Chatwoot.
- Rellena URL de tu servidor Chatwoot (ejemplo:
https://chat.tudominio.com, sin barra final). - Opcional: Account ID — si lo configuras, solo se aceptarán mensajes de esa cuenta de Chatwoot.
- Deja pendientes API Access Token y Webhook Secret; los obtendrás en Chatwoot en los pasos siguientes.
- 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:
- Ve a Settings → Integrations → Webhooks y crea un webhook nuevo.
- Pega la URL del Webhook que copiaste de EasyChatBot.
- Marca todos los eventos disponibles (recomendado).
- Copia el Webhook Secret que te muestra Chatwoot y pégalo en EasyChatBot, en el campo Webhook Secret.
- 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.
- Vincula el Agent Bot al inbox (WhatsApp, widget web, etc.) según la documentación de Chatwoot 4.15.
- Guarda en ambos lados y prueba enviando un mensaje de prueba desde el canal conectado.
En la bandeja de Chatwoot la conversación puede aparecer como Sin asignar aunque el Agent Bot esté vinculado al inbox. Es normal: el bot de EasyChatBot sigue respondiendo automáticamente.
Documentación oficial de Chatwoot: How to use webhooks.
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
- En Chatwoot, ve a Settings → Bots y crea un Agent Bot (o usa uno existente).
- Copia su API Access Token y pégalo en EasyChatBot en el campo API Access Token.
- Asocia ese Agent Bot al inbox de tu canal (WhatsApp, widget web, etc.).
No mezcles estas claves
| Campo en EasyChatBot | De dónde sale |
|---|---|
| Webhook Secret | Al crear el webhook en Settings → Integrations → Webhooks |
| API Access Token | Del Agent Bot en Settings → Bots |
| Access Token WhatsApp (opcional) | La «Clave de API» del inbox WhatsApp en Chatwoot / Meta Business (empieza por EAA…) |
Son tres credenciales distintas. Si las intercambias, el bot dejará de responder o verás mensajes duplicados.
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.
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
| Situación | Qué pasa |
|---|---|
| El contacto escribe y nadie humano está atendiendo | El bot responde con IA. |
| Un agente se asigna la conversación en Chatwoot | El contacto recibe «Te atenderá {nombre}.»; la conversación pasa a Control humano y el bot deja de contestar solo. |
| Un agente humano responde desde Chatwoot | El mensaje queda en el historial de EasyChatBot; el bot no interviene. |
| El agente deja de estar asignado en Chatwoot | El bot retoma la conversación y vuelve a responder automáticamente. |
| La conversación se cierra en Chatwoot | EasyChatBot la marca como Terminada. Si el contacto escribe de nuevo, empieza una conversación nueva. |
| El contacto pide hablar con una persona | Si tienes la acción Hablar con Asesor en una intención, el bot pausa, envía el mensaje de handoff y deja la conversación en cola para agentes en Chatwoot. |
| El token del Agent Bot dejó de ser válido | El bot no puede enviar respuestas; la conversación pasa a Control humano hasta que corrijas el token en EasyChatBot. |
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:
| Dónde | Qué necesitas |
|---|---|
| Panel EasyChatBot (detalle de conversación) | Nada extra — aparece automáticamente mientras el bot piensa. |
| Widget web de Chatwoot | Agent Bot bien configurado y vinculado al inbox. |
| WhatsApp del contacto | Campos opcionales Access Token WhatsApp y Phone Number ID (ver sección WhatsApp). |
En el panel de EasyChatBot, el mensaje del contacto aparece antes de los tres puntos mientras el bot procesa la respuesta.
En WhatsApp, 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 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.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.
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.