Para integrar WhatsApp, Facebook Messenger e Instagram en Chatwoot autohospedado necesitas algo más que crear tres bandejas. Debes identificar los activos correctos de Meta, conectarlos a la cuenta de la empresa y comprobar que los mensajes entran, reciben respuesta y conservan sus archivos.
Este recorrido recoge lo que aprendimos al conectar esos canales y trasladar una operación a Chatwoot 4.18.0 en octubre de 2026. La enseñanza principal fue separar tres trabajos: habilitar los canales, recuperar el historial y comprobar los accesos. Uno puede funcionar mientras otro todavía necesita trabajo. Una bandeja visible o un consentimiento completado no prueban por sí solos que la integración esté lista.
Partimos de una instalación con HTTPS, base de datos y procesos de trabajo operativos. La guía no sustituye la instalación del servidor ni los requisitos de revisión y permisos de Meta.
Una instalación, una cuenta por empresa y una bandeja por canal
En Chatwoot, una cuenta organiza la operación de una empresa y sus bandejas reciben los distintos canales. Una persona que administra varias cuentas puede cambiar entre ellas; los agentes de un cliente deben conservar únicamente las membresías que necesitan.
Esta distinción evita una confusión que apareció durante la conexión de Facebook: el selector de páginas autorizadas por Meta muestra los activos accesibles para el administrador que está conectando. Esa lista no demuestra que las conversaciones de esas páginas ya estén dentro de una misma cuenta de Chatwoot. El control decisivo es qué página se conecta a qué bandeja y a qué cuenta, y quién puede acceder después.
| Elemento | Qué debes comprobar |
|---|---|
| Cuenta de Chatwoot | Corresponde a la empresa que recibirá las conversaciones. |
| Bandeja | Representa el número, la página o el perfil que estás conectando. |
| Usuario | Tiene el rol y las membresías necesarios para su trabajo. |
| Activo de Meta | Su identificador coincide con el número, la página o el perfil aprobado. |
No uses solamente los nombres para hacer esa correspondencia: dos páginas pueden parecerse, una persona puede administrar varias marcas y un perfil personal puede estar abierto donde esperabas encontrar el comercial.
1. Preparar el inventario antes de autorizar conexiones
Antes de abrir OAuth, registra la cuenta destino, las bandejas existentes, sus usuarios y los activos del proveedor. Si vas a migrar, añade el origen que seguirá disponible para recuperar datos y la configuración que permitiría volver atrás.
- WhatsApp: número visible, identificador del número, cuenta de WhatsApp Business y aplicación utilizada.
- Facebook: página e identificador exactos, aplicación y acceso administrativo existente.
- Instagram: nombre de usuario y perfil profesional, aplicación y método de inicio de sesión.
- Chatwoot: cuenta, bandeja, integrantes y responsable que completará las verificaciones de Meta.
Prepara también un texto de prueba y una imagen propios. El remitente debe controlar su cuenta personal y conocer el destinatario exacto. Esto permite encontrar la prueba sin responder accidentalmente a una conversación comercial.
2. Configurar Meta para la instalación que realmente vas a usar
La configuración de una instalación propia no aparece automáticamente al instalar Chatwoot. Revisa la aplicación, sus productos, los dominios permitidos, la dirección de retorno del inicio de sesión y las suscripciones de eventos que correspondan al canal. Chatwoot documenta los requisitos de Facebook Messenger y de Instagram Business Login.
Conserva una dirección canónica coherente para los callbacks. Un dominio de acceso con la marca de un cliente no significa que debas cambiar todas las URL de OAuth y webhooks a ese dominio. Un desajuste puede impedir el retorno del consentimiento o dirigir los eventos a otra instalación.
Las claves se introducen en la configuración privada. No deben aparecer en capturas, ejemplos, correos de coordinación o artículos. El titular debe completar sus contraseñas, segundo factor y consentimientos desde sus propias sesiones.
3. Conectar WhatsApp y probar el recorrido completo
Distingue una conexión de WhatsApp Cloud API existente del registro mediante coexistencia con WhatsApp Business. El recorrido y la elegibilidad pueden cambiar; no asumas que cualquier número puede seguir el mismo formulario.
En una migración, identifica qué aplicación recibe los eventos del número y conserva su configuración anterior antes del corte. No dejes dos sistemas respondiendo por accidente. Conecta el activo correcto dentro de la cuenta destino y verifica una entrada desde un WhatsApp controlado por el propietario.
Después responde desde Chatwoot y envía la imagen acordada. Comprueba la entrega y pide al destinatario que confirme que la imagen abre. Aceptación del envío y recepción en el teléfono son comprobaciones diferentes.
Publicamos por separado el recorrido de WhatsApp Business y Chatwoot por coexistencia, con las capturas de nuestra prueba. Si ese es tu escenario, úsalo como complemento.
4. Conectar Facebook Messenger a la cuenta correcta
Abre la cuenta de la empresa en Chatwoot antes de iniciar la conexión. En el consentimiento de Meta, conserva los accesos existentes que siguen en uso y selecciona únicamente los activos necesarios. Al volver a Chatwoot, elige la página cuyo identificador registraste en el inventario.
Comprueba las bandejas existentes antes de crear otra. Una bandeja nueva puede empezar a recibir mientras el historial queda en una antigua; eso requiere conciliación, no una eliminación apresurada.
La prueba debe salir de un perfil personal hacia la página correcta. Nos ocurrió que un texto que mencionaba una marca se había enviado a otra página. El contenido del mensaje no acredita su destinatario. Revisa el encabezado del chat y localiza la entrada en la cuenta y el canal correspondientes.
Si importas conversaciones, conserva los identificadores originales y comprueba su correspondencia antes de habilitar respuestas. Una coincidencia de nombre no basta para decidir a qué persona se enviará un mensaje.
5. Separar invitación, aceptación y OAuth en Instagram
Instagram mostró con claridad la diferencia entre tener un permiso y tener una conexión operativa. Verifica el perfil profesional correcto y el método de conexión configurado en tu versión de Chatwoot.
Si realizas una prueba para la que se requiere un evaluador de Instagram, el orden es:
- Añadir el perfil correcto al rol de evaluación de la aplicación correspondiente.
- Entrar como ese perfil en Instagram y aceptar personalmente la invitación y sus condiciones.
- Volver a iniciar OAuth para obtener el acceso con el rol ya aceptado.
- Autorizar el acceso de perfil y mensajes que requiere la integración y comprobar el retorno a Chatwoot.


En nuestro recorrido apareció un error durante el intercambio del token. Lo resolvimos revisando el rol y repitiendo el consentimiento después de aceptarlo, sin cambiar el método HTTP de la integración. No conviertas ese mensaje de error en un diagnóstico universal: revisa también los permisos, la aplicación, la dirección de retorno y la configuración servida.
El rol de evaluador sirve para el escenario de prueba correspondiente. No sustituye la revisión de la aplicación ni los permisos necesarios para atender perfiles de terceros en producción. La documentación oficial distingue esas etapas.
Para probar, envía desde otro perfil controlado por el propietario. La sesión con la que autorizaste Instagram puede estar abierta como la propia empresa; enviar desde ella no comprueba la recepción de un cliente externo.
6. Hacer el corte por canal y cerrar después el historial
Intentar terminar toda la importación mientras el origen sigue acumulando mensajes puede convertir la migración en una persecución interminable. Nos resultó más útil preparar un avance verificable, trasladar la recepción y cerrar después el intervalo histórico que faltaba.
- Preparar: inventario, recuperación comprobada y copia inicial con identificadores estables.
- Cortar: trasladar el receptor del canal y comprobar que el sistema anterior no sigue emitiendo respuestas.
- Probar: entrada, respuesta y adjunto mediante una conversación controlada.
- Conciliar: importar el tramo pendiente y reconocer los mensajes que ya llegaron al destino para no duplicarlos.
- Cerrar: revisar faltantes y recuperación antes de retirar el origen.
Este orden no permite saltarse el respaldo o las pruebas del importador. Las notas privadas deben conservar su visibilidad, los autores no se deducen por apodo y una repetición de la misma operación no debe duplicar mensajes. Si el proveedor limita las consultas, usa checkpoints y respeta su cuota en lugar de reiniciar exportaciones completas.
7. Guardar los adjuntos en S3 sin romper las conversaciones
El almacenamiento compatible con S3 puede reducir el crecimiento del disco de la aplicación. En nuestro despliegue usamos Hetzner Object Storage. La configuración depende del servicio disponible en la versión instalada: revisa el soporte de almacenamiento de Chatwoot y la configuración del proveedor compatible que elijas.
El proceso web y el worker deben recibir la misma configuración de servicio, bucket, endpoint, región y credenciales. Copiar archivos al bucket no cambia por sí solo las referencias que la aplicación utiliza para encontrarlos.
- Genera un inventario de objetos con tamaños y checksums.
- Compara la copia con el origen y comprueba la integridad. No supongas que cualquier ETag es un MD5 del archivo completo; confirma su significado o verifica el contenido mediante otro checksum.
- Abre desde Chatwoot imágenes, audios, videos y documentos históricos. Repite con archivos nuevos.
- Comprueba los enlaces que devuelve la aplicación, no solamente que el objeto exista en el bucket.
- Conserva los archivos locales hasta terminar la revisión y medir el espacio realmente recuperable.
La documentación de integridad de objetos de S3 explica las comprobaciones disponibles. En un servicio compatible hay que confirmar cuáles soporta su implementación.
El bucket operativo no es por sí solo un respaldo independiente. Si los nuevos adjuntos existen únicamente allí, el respaldo del disco del servidor ya no los incluye. La recuperación debe abarcar la base de datos y los objetos, con una copia independiente y una restauración comprobada.
Si un archivo ya no existe en el origen y no hay otra copia, registra el faltante. No lo sustituyas por un archivo inventado ni presentes ese mensaje como íntegramente recuperado.
8. Usar dominios de marca sin confundirlos con el aislamiento
Un dominio como chat.cliente.example puede dar una entrada reconocible a la empresa. La separación de conversaciones depende de las cuentas, membresías y autorizaciones de Chatwoot. Una dirección distinta no crea por sí sola una frontera de acceso.
Si añades reglas propias de proxy o navegación, prueba el cambio de cuenta, los enlaces directos, los callbacks y las solicitudes de API. Un usuario con varias membresías puede necesitar ir al dominio correspondiente a la cuenta que elige. Entre dominios distintos también puede necesitar iniciar sesión de nuevo.
Documenta cualquier configuración adicional y repite sus comprobaciones al actualizar Chatwoot. El comportamiento que hayas implementado para tus dominios no debe presentarse como una función nativa disponible de la misma forma en todas las instalaciones.
La matriz mínima para dar un canal por listo
Guarda el resultado de cada fila por empresa y canal. Una prueba aprobada de WhatsApp no acredita Facebook o Instagram.
| Comprobación | Evidencia esperada |
|---|---|
| Acceso | El usuario entra en la cuenta correcta y ve las bandejas que necesita. |
| Recepción | La prueba del remitente controlado aparece en el canal correcto. |
| Respuesta | El destinatario confirma la respuesta enviada desde Chatwoot. |
| Adjunto nuevo | El destinatario abre la imagen o documento de prueba. |
| Historial y archivos | Las muestras antiguas abren y los faltantes están identificados. |
| Reversión | La configuración anterior y los datos necesarios para volver están conservados. |
La diferencia entre una integración que parece terminada y una que puede usarse está en esas comprobaciones. Nuestro criterio es cerrar cada canal con evidencia y tratar por separado lo que siga pendiente del historial, de los usuarios o de la recuperación.
Preguntas frecuentes
¿Necesito otra instalación de Chatwoot para cada empresa?
No necesariamente. Una instalación puede organizar varias cuentas con sus propias bandejas y usuarios. Debes verificar sus membresías y permisos; un dominio de marca no reemplaza esos controles.
¿Aceptar OAuth significa que ya llegan los mensajes?
No. El consentimiento concede el acceso correspondiente, pero todavía debes comprobar los eventos, la cuenta destino y una conversación real de entrada y salida.
¿Puedo activar los canales antes de recuperar todo el historial?
Sí, si preparaste un corte controlado, un avance histórico verificable y una reversión. Después debes conciliar el intervalo restante y evitar los duplicados. La recuperación incompleta del historial debe seguir identificada.
¿Mover los adjuntos a S3 permite borrar inmediatamente la copia local?
No. Primero comprueba inventario, integridad, enlaces históricos y nuevos, respaldo independiente y restauración. Después evalúa la retirada y el espacio que realmente se liberaría.
Si estás eligiendo infraestructura, consulta también nuestro ensayo de Chatwoot con 60 agentes simulados. Es una prueba distinta, con sus condiciones y límites, no una garantía de capacidad para cualquier despliegue.
Recorrido documentado con Chatwoot 4.18.0 en octubre de 2026. Las pantallas y los requisitos del proveedor pueden cambiar. La portada utiliza la demostración oficial de Chatwoot en español; las dos capturas de invitaciones proceden del procedimiento real.
Siguiente paso recomendado
Lleva esta conversación a un WhatsApp mejor atendido
Describe las consultas que más se repiten y el flujo que hoy consume tiempo. Podremos evaluar automatización, derivación humana y seguimiento.