Transfert des SMS reçus

Chaque SMS reçu par vos téléphones arrive dans Conversations. Si un autre outil doit aussi y réagir, la passerelle peut prévenir cet outil de chaque SMS reçu en appelant son adresse web : un webhook qui écoute l'événement message.received.

Les webhooks se gèrent sur la page Webhooks, dans la section Automatisation de la barre latérale, juste sous Règles. Ce guide couvre le cas le plus courant, le transfert des SMS reçus. Tout ce que la page fait d'autre (autres événements, chaque champ, le journal des livraisons et ses filtres) est décrit dans Configurer un webhook depuis le dashboard.

À quoi sert le transfert

Créer un ticket dans votre outil de support quand un client écrit.
Lancer un scénario n8n ou Make à chaque SMS entrant : l'inscrire dans un tableur, alerter un canal d'équipe, répondre depuis un assistant IA.
Tenir à jour l'historique des échanges de votre CRM.

Pour des réponses automatiques dans la passerelle elle-même, aucun outil externe n'est nécessaire : voir Automatisation.

Comment ça marche

Un téléphone reçoit un SMS et le remet à la passerelle.
Pour chaque webhook actif qui écoute message.received, la passerelle met une livraison en file et appelle votre adresse, en général en quelques secondes.
Votre outil répond par un statut 2xx : la livraison est Livré. Toute autre réponse, une absence de réponse en 10 secondes ou une redirection compte comme un échec, et la passerelle réessaie plus tard (5 tentatives sur 1 h 15 environ).

Ce que reçoit votre adresse

L'appel porte les identifiants du message, jamais son contenu :

{
  "event": "message.received",
  "at": "2026-09-21T08:14:03.512Z",
  "id": "0192f0c4-9d2a-7e11-b3c5-6a8f1e2d4c70",
  "conversationId": "0192f0a1-44be-7a02-8e19-3c7d5b9f0e21",
  "deviceId": "0192ef77-1c0d-7b3a-a5e4-9f2c8d1b6e03"
}

Le texte du SMS et le numéro complet ne quittent jamais la passerelle dans cet appel. Votre outil les lit par l'API, avec une clé dont vous choisissez la portée : GET /api/v1/messages/{id} renvoie le message. Ainsi, une adresse divulguée ne révèle rien, et vous décidez exactement quel outil peut lire quoi. Voir Utiliser l'API et Clés API.

Chaque appel est signé : votre outil vérifie l'en-tête X-Signature avec le secret de signature et refuse un appel de plus de cinq minutes. L'encadré Vérifier la signature de la page Webhooks résume les contrôles, et Vérifier la signature donne des exemples de code.

Transférer les SMS reçus en quatre étapes

Ouvrez Webhooks dans la barre latérale et cliquez sur Transférer les SMS reçus. Le formulaire s'ouvre avec l'événement message.received déjà coché.
Renseignez Nom (pour vous) et URL (l'adresse de votre outil). Laissez Méthode sur POST sauf si votre outil attend autre chose, et ajoutez un En-tête personnalisé si votre outil exige un jeton.
Laissez Secret de signature (facultatif) vide et cliquez sur Créer.
La fenêtre Secret de signature montre le secret une seule fois, avec un bouton de copie. Collez-le dans votre outil, puis cliquez sur J'ai copié le secret : il ne sera plus jamais affiché.

Chaque champ porte un petit « i » qui l'explique au survol. Vous pouvez cocher d'autres événements dans le même formulaire, par exemple message.failed pour être aussi prévenu des envois en échec.

Suivre ce qui a été envoyé

Dans la liste, la colonne État dit si le webhook est Actif, En pause (vous l'avez désactivé) ou Coupé après échecs (la passerelle l'a désactivé après 100 livraisons abandonnées d'affilée), et Échecs consécutifs compte les livraisons abandonnées depuis le dernier succès.
L'onglet Journal des livraisons liste chaque appel avec la réponse de votre outil. Filtrez-le sur l'Événement message.received, ou utilisez Voir les livraisons dans le menu de la ligne du webhook.
Rejouer la livraison renvoie une livraison, signée à nouveau, typiquement après avoir corrigé un bogue de votre outil pour traiter les messages qu'il a manqués.
Mettre en pause et Réactiver, dans le menu de la ligne, arrêtent et relancent le transfert. Les SMS reçus pendant une pause ne sont pas envoyés plus tard : lisez-les par l'API (GET /api/v1/messages?direction=in).

Qui peut faire quoi

Rôle	Page Webhooks
Lecture seule	Voir la liste et le journal des livraisons
Opérateur, Superadministrateur	Créer, modifier, mettre en pause, réactiver, supprimer, rejouer

En cas de problème

Ce que vous voyez	Pourquoi, et que faire
Échec avec une erreur qui parle d'adresse bloquée ou locale	L'URL vise `localhost` ou la machine elle-même. Utilisez son adresse réseau (par exemple `http://192.168.1.20:5678/...`)
Échec avec le code HTTP `301` ou `302`	Les redirections ne sont pas suivies. Mettez l'adresse finale dans URL (souvent `https://` au lieu de `http://`)
Échec avec le code HTTP `401` ou `403`	Votre outil attend un jeton : ajoutez-le dans En-têtes personnalisés, ou votre outil refuse la signature
Votre outil refuse la signature	Mauvais secret, ou signature calculée sur un corps resérialisé. Signez le corps brut, tel que reçu
Votre outil refuse les appels comme trop anciens	Son horloge dérive. Synchronisez-la (NTP) : la tolérance est de cinq minutes
Coupé après échecs	Votre outil a échoué 100 livraisons d'affilée. Corrigez-le, puis Réactiver, puis rejouez ce qu'il a manqué
La charge utile ne contient pas de texte	C'est normal : lisez le message avec `GET /api/v1/messages/{id}`

D'autres causes, la table des nouvelles tentatives et les adresses que la passerelle refuse d'appeler sont dans Webhooks.