Alojar Chatwoot en un VPS: soporte al cliente omnicanal

Las soluciones SaaS de atención al cliente tienen un modelo de negocio sencillo: usted paga por agente y por canal, y los datos de sus clientes se almacenan en los servidores del proveedor. Para una agencia web o una pyme, esto supone rápidamente varios cientos de dólares al mes en cuanto el equipo supera las dos o tres personas. Chatwoot invierte esta ecuación: usted despliega la plataforma en su propio VPS, invita a tantos agentes como necesite y conecta todos sus canales sin coste adicional. Sus intercambios con los clientes permanecen en su infraestructura — un argumento de peso para el cumplimiento del RGPD, la confianza del cliente y la soberanía de los datos.

Chatwoot funciona con una pila Ruby on Rails + Sidekiq + PostgreSQL 15 + Redis 7, es decir, cuatro contenedores Docker. Prevea un VPS con 2 GB de RAM como mínimo (4 GB recomendados para equipos de más de 10 agentes). Ubuntu 24.04 con Docker es el camino más rápido. En el lado de la red, prepare un subdominio — support.your-domain.com, por ejemplo — y un reverse proxy (Nginx o Caddy) para activar el HTTPS. Chatwoot exige un FRONTEND_URL en HTTPS para que las redirecciones OAuth, los enlaces de los correos electrónicos y el script del widget de livechat funcionen correctamente.

Antes de empezar, verifique que Docker Compose v2 esté instalado (docker compose version): Chatwoot v4 utiliza la sintaxis docker compose (con espacio) y no el antiguo comando docker-compose.

Chatwoot permite centralizar múltiples canales en una sola interfaz. Cada canal crea una bandeja de entrada independiente, visible en la barra lateral y asignable a un equipo dedicado.

Correo electrónico (SMTP/IMAP): en Ajustes → Bandejas de entrada → Correo electrónico, introduzca su dirección entrante y las credenciales IMAP. Chatwoot consulta el buzón cada dos minutos y crea una conversación por hilo. Las respuestas se envían por SMTP conservando el mismo hilo.

DMs de Twitter/X: conecte una cuenta mediante la API Twitter v2 (clave de API + secreto + token de acceso). Los mensajes directos entrantes aparecen en tiempo real mediante webhook. Nota: el acceso a la API Twitter v2 requiere una suscripción de desarrollador Basic o superior.

Teléfono y WebRTC: Chatwoot v4.17 migró su integración de videollamadas de Dyte a Cloudflare RealtimeKit. Si utiliza las videollamadas, reconfigure la integración en Ajustes → Integraciones → Cloudflare Calls con su App ID y App Token.

Canal API: para integraciones personalizadas (chatbot, CRM propio), cree una bandeja de entrada de tipo API. Expone un endpoint REST para recibir mensajes y usted envía las respuestas mediante POST /api/v1/accounts/{id}/conversations/{conv_id}/messages. Es la puerta de entrada para conectar cualquier fuente externa.

Chatwoot ofrece varios niveles de integración para insertarse en su stack existente.

Webhooks: en Ajustes → Integraciones → Webhooks, añada la URL de su endpoint. Chatwoot lanza un evento JSON en cada conversación creada, mensaje recibido o cambio de estado. Útil para sincronizar tickets con un CRM, lanzar un flujo de trabajo n8n o registrar conversaciones en su base de datos.

Notificaciones Slack: conecte un workspace Slack mediante OAuth en Ajustes → Integraciones → Slack. Las nuevas conversaciones y menciones en Chatwoot generan una notificación en el canal Slack elegido. Sus agentes no pierden ningún mensaje ni fuera de la interfaz.

API REST: todos los recursos de Chatwoot (conversaciones, contactos, mensajes, equipos, etiquetas) se exponen mediante una API REST v1 documentada en /swagger. Autenticación por token (user_access_token o clave API de agente). Casos de uso comunes: importar contactos desde un CRM, generar informes de conversaciones resueltas, actualizar automáticamente atributos de contacto.

Zapier / Make (ex-Integromat): Chatwoot dispone de conectores nativos en Zapier y Make para lanzar acciones sin código. Ejemplo: nueva conversación en Chatwoot → crear una oportunidad en el CRM → notificar al equipo comercial por correo.

Las actualizaciones menores (patch releases como v4.17.0 → v4.17.1) son seguras y suelen contener correcciones de seguridad: planifíquelas en las 48 horas siguientes a su publicación.

Para una actualización de parche:

docker compose pull
docker compose down
docker compose up -d
docker compose exec rails bundle exec rails db:migrate

Revise los logs (docker compose logs web --tail=30) y pruebe el envío de un mensaje en cada canal.

Para una actualización mayor (v3 → v4), el proceso es más delicado: v4 introduce migraciones de esquema PostgreSQL bloqueantes (tablas mentions y conversation_participants reestructuradas). Nunca ejecute docker compose pull && docker compose up -d sin una copia de seguridad previa en una versión mayor.

Buena práctica: fije siempre una versión concreta en docker-compose.yml (chatwoot/chatwoot:v4.17.1 en lugar de latest) para controlar exactamente lo que se ejecuta en producción y evitar actualizaciones silenciosas.

Chatwoot v4, publicado en junio de 2026, introduce la nueva interfaz «Nova UI» y varias migraciones de esquema PostgreSQL bloqueantes. Una actualización en caliente desde v3 rompe sistemáticamente la instancia si se hace sin preparación — es el tema de la incidencia oficial #12088, que recoge los casos más habituales.

La razón principal de la rotura: v4 renombra la tabla mentions y reestructura la tabla conversation_participants. Un docker compose pull && docker compose up -d sin copia de seguridad previa lanza las migraciones automáticamente; si una migración falla a mitad de camino (timeout, restricción de FK no satisfecha), la base de datos queda en un estado intermedio y Chatwoot ya no arranca.

En la práctica, hay tres categorías de instancias en riesgo: las que funcionan en v3 con un volumen de conversaciones superior a 50 000 (las migraciones masivas son lentas y pueden superar el timeout de 30 s de Rails), las que tienen columnas personalizadas no documentadas en la tabla contacts, y las que utilizan Sidekiq Pro (eliminado de la Community Edition en v4 — los jobs en espera en el momento de la actualización se pierden).

Workers de Sidekiq bloqueados. Si los correos salientes dejan de enviarse o los webhooks dejan de dispararse, Sidekiq probablemente está paralizado o sus workers están agotados. Compruebe mediante la interfaz Sidekiq Web (/sidekiq) o los logs: docker compose logs sidekiq --tail=50. La causa más frecuente es una cola mailers saturada. Reinicie el worker: docker compose restart sidekiq. Si el problema persiste, verifique la conexión Redis (docker compose exec redis redis-cli ping debe responder PONG).

Redis connection refused. Si Rails y Sidekiq no arrancan con Redis::CannotConnectError, el contenedor Redis no está listo. Compruebe su estado: docker compose ps redis. Un contenedor en Restarting indica un problema de volumen o permiso. Elimine el volumen Redis y reinicie si los datos Redis son transitorios (los jobs en cola se perderán).

ActionCable WebSocket sin conectar. El widget de livechat muestra «conexión perdida» o los agentes no reciben mensajes en tiempo real. Causa probable: el reverse proxy no reenvía las cabeceras WebSocket. Con Nginx, añada al bloque location:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Con Caddy, la configuración reverse_proxy localhost:3000 gestiona los WebSockets automáticamente.

Migración atascada a mitad. Si rails db:migrate se detiene con error, no vuelva a intentarlo de inmediato. Identifique la migración fallida en el mensaje de error, corrígala manualmente o sáltesela (rails db:migrate:up VERSION=<timestamp>), luego reintente. Como último recurso, restaure la copia de seguridad tomada antes de la migración.