Héberger Chatwoot sur un VPS : support client omnicanal

Les solutions SaaS de support client ont un modèle économique simple : vous payez par agent et par canal, et vos données de clients sont stockées sur leurs serveurs. Pour une agence web ou une PME, cela représente rapidement plusieurs centaines de dirhams par mois dès que l'équipe dépasse deux ou trois personnes. Chatwoot inverse ce calcul : vous déployez la plateforme sur votre propre VPS, vous invitez autant d'agents que nécessaire, et vous connectez tous vos canaux sans frais supplémentaires. Vos échanges clients restent sur votre infrastructure — un argument de poids pour la conformité RGPD, la confiance client et la souveraineté des données.

Chatwoot tourne avec une stack Ruby on Rails + Sidekiq + PostgreSQL 15 + Redis 7, soit quatre conteneurs Docker. Prévoyez un VPS avec au minimum 2 Go de RAM (4 Go recommandés pour des équipes de plus de 10 agents). Ubuntu 24.04 avec Docker est le chemin le plus rapide. Côté réseau, préparez un sous-domaine — support.votre-domaine.com par exemple — et un reverse proxy (Nginx ou Caddy) pour activer le HTTPS. Chatwoot exige un FRONTEND_URL en HTTPS pour que les redirections OAuth, les liens dans les e-mails et le script du widget livechat fonctionnent correctement.

Avant de démarrer, vérifiez que Docker Compose v2 est installé (docker compose version) : Chatwoot v4 utilise la syntaxe docker compose (avec espace) et non l'ancienne commande docker-compose.

Chatwoot permet de centraliser plusieurs canaux dans une seule interface. Chaque canal crée une boîte de réception indépendante, visible dans la barre latérale et assignable à une équipe dédiée.

E-mail (SMTP/IMAP) : dans Paramètres → Boîtes de réception → E-mail, saisissez votre adresse entrante et les identifiants IMAP. Chatwoot interroge la boîte toutes les deux minutes et crée une conversation par fil. Les réponses partent via SMTP en conservant le même fil.

Twitter/X DMs : connectez un compte via l'API Twitter v2 (clé API + secret + token d'accès). Les messages directs entrants apparaissent en temps réel via webhook. Note : l'accès à l'API Twitter v2 nécessite un abonnement développeur Basic ou supérieur.

Téléphone et WebRTC : Chatwoot v4.17 a migré son intégration d'appels vidéo de Dyte vers Cloudflare RealtimeKit. Si vous utilisez les appels vidéo, reconfigurez l'intégration dans Paramètres → Intégrations → Cloudflare Calls et renseignez votre App ID et App Token.

API channel : pour les intégrations personnalisées (chatbot, CRM maison), créez une boîte de réception de type API. Elle expose un endpoint REST pour recevoir les messages et vous renvoyez les réponses via POST /api/v1/accounts/{id}/conversations/{conv_id}/messages. C'est la porte d'entrée pour brancher n'importe quelle source externe.

Chatwoot offre plusieurs niveaux d'intégration pour s'insérer dans votre stack existante.

Webhooks : dans Paramètres → Intégrations → Webhooks, ajoutez l'URL de votre endpoint. Chatwoot déclenche un événement JSON à chaque conversation créée, message reçu ou statut changé. Utile pour synchroniser les tickets vers un CRM, déclencher un workflow n8n ou enregistrer les conversations dans votre base.

Notifications Slack : connectez un workspace Slack via OAuth dans Paramètres → Intégrations → Slack. Les nouvelles conversations et mentions envoyées dans Chatwoot génèrent une notification dans le canal Slack de votre choix. Vos agents ne ratent aucun message même hors de l'interface.

API REST : toutes les ressources Chatwoot (conversations, contacts, messages, équipes, étiquettes) sont exposées par une API REST v1 documentée à /swagger. Authentification par token (user_access_token ou clé API d'agent). Cas d'usage courants : import de contacts depuis un CRM, rapport des conversations résolues, mise à jour automatique des attributs de contact.

Zapier / Make (ex-Integromat) : Chatwoot dispose de connecteurs natifs sur Zapier et Make pour déclencher des actions sans code. Exemple : nouvelle conversation Chatwoot → créer une opportunité dans votre CRM → notifier l'équipe commerciale par e-mail.

Les mises à jour mineures (patch releases comme v4.17.0 → v4.17.1) sont sans risque et contiennent souvent des correctifs de sécurité : planifiez-les dans les 48 heures suivant leur publication.

Pour une mise à jour de patch :

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

Vérifiez ensuite les logs (docker compose logs web --tail=30) et testez l'envoi d'un message sur chaque canal.

Pour une mise à jour majeure (v3 → v4), la procédure est plus délicate : v4 introduit des migrations de schéma PostgreSQL bloquantes (tables mentions et conversation_participants restructurées). Ne faites jamais docker compose pull && docker compose up -d sans sauvegarde préalable sur une version majeure.

Bonne pratique : épinglez toujours une version précise dans docker-compose.yml (chatwoot/chatwoot:v4.17.1 plutôt que latest) afin de contrôler exactement ce qui tourne en production et d'éviter les mises à jour silencieuses.

Chatwoot v4, sorti en juin 2026, introduit la nouvelle interface « Nova UI » et plusieurs migrations de schéma PostgreSQL bloquantes. Une montée de version à chaud depuis v3 casse systématiquement l'instance si elle est faite sans préparation — c'est le sujet de l'issue officielle #12088, qui recense les cas les plus courants.

La raison principale de la casse : v4 renomme la table mentions et restructure la table conversation_participants. Un docker compose pull && docker compose up -d sans sauvegarde préalable lance les migrations automatiquement ; si une migration échoue à mi-chemin (timeout, contrainte de FK non satisfaite), la base se retrouve dans un état intermédiaire et Chatwoot ne démarre plus.

En pratique, trois catégories d'instances sont à risque : celles qui tournent en v3 avec un volume de conversations supérieur à 50 000 (les migrations de masse sont lentes et peuvent dépasser le timeout Rails de 30 s), celles qui ont des colonnes personnalisées non documentées dans la table contacts, et celles qui utilisent Sidekiq Pro (supprimé de la Community Edition en v4 — les jobs en attente au moment de la mise à jour sont perdus).

Sidekiq workers bloqués. Si les e-mails sortants ne partent plus ou si les webhooks ne se déclenchent plus, Sidekiq est probablement en attente ou ses workers sont épuisés. Vérifiez via l'interface Sidekiq Web (/sidekiq) ou les logs : docker compose logs sidekiq --tail=50. La cause la plus fréquente est une file mailers saturée. Redémarrez le worker : docker compose restart sidekiq. Si le problème persiste, vérifiez la connexion Redis (docker compose exec redis redis-cli ping doit répondre PONG).

Redis connection refused. Si Rails et Sidekiq ne démarrent pas avec Redis::CannotConnectError, le conteneur Redis n'est pas prêt. Vérifiez son état : docker compose ps redis. Un conteneur en Restarting indique un problème de volume ou de permission. Supprimez le volume Redis et relancez si les données Redis sont transitoires (les jobs en attente seront perdus).

ActionCable WebSocket non connecté. Le widget livechat affiche « connexion perdue » ou les agents ne reçoivent pas les messages en temps réel. Cause probable : le reverse proxy ne passe pas les headers WebSocket. Avec Nginx, ajoutez dans votre block location :

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

Avec Caddy, la configuration reverse_proxy localhost:3000 gère automatiquement les WebSockets.

Migration bloquée à mi-chemin. Si rails db:migrate s'arrête en erreur, n'essayez pas de relancer immédiatement. Identifiez la migration fautive dans le message d'erreur, corrigez-la manuellement ou sautez-la (rails db:migrate:up VERSION=<timestamp>), puis rejouez. En dernier recours, restaurez la sauvegarde prise avant la migration.