Deux charges utiles de webhook portent les événements de messagerie. Un événement de statut de livraison (DLR) rapporte le résultat d'un message — message_id, une énumération de statut (accepted, delivered, undelivered, expired, rejected), une raison d'erreur et des timestamps. Un événement entrant (MO) rapporte un message qu'un abonné vous a envoyé. Les deux sont les équivalents HTTP des accusés deliver_sm SMPP et des messages mobile-originated.
- Votre applicationEnvoi via REST API ou SMPP
- Plateforme BroadNetValide, route et facture chaque message
- SMSC de l’opérateurConnexion directe opérateur
- Terminal de l'abonnéLe message est livré
Deux familles d'événements : statut et entrant
Une plateforme de messagerie émet deux callbacks fondamentalement différents. Un événement de statut de livraison (DLR, accusé de livraison) est le suivi asynchrone d'un message que vous avez envoyé : il vous dit ce qui lui est finalement arrivé dans le réseau opérateur. Un événement entrant (MO, mobile-originated) est non sollicité — un message qu'un abonné a envoyé à l'un de vos numéros, ou une réponse à une campagne. Ils partagent le transport et la signature de webhook, mais leurs schémas et leur signification diffèrent, si bien qu'un consommateur robuste bifurque sur un discriminant de type d'événement avant d'analyser le reste. Les deux sont l'expression, à la couche HTTP, de ce que SMPP livre sous forme de PDU deliver_sm : un drapeau d'accusé distingue un DLR d'un MO sur le fil, et la même distinction est un champ d'événement explicite sur HTTP.
Charge utile de statut de livraison (DLR)
Une charge utile de statut de livraison se corrèle à l'envoi d'origine par le message_id attribué par le serveur et rapporte un statut tiré d'une petite énumération, plus la raison et les timestamps qui vous permettent de mesurer la latence et de rapprocher la facturation. L'énumération de statut en est le cœur : elle distingue un état intermédiaire accepted/enroute des états terminaux, et sépare un delivered positif des multiples façons dont un message peut échouer. Les états négatifs terminaux portent un code d'erreur et une raison lisible par un humain, pour qu'un consommateur puisse décider si la destination est définitivement mauvaise (la supprimer) ou si l'échec était transitoire (réémission sûre). Les timestamps incluent typiquement le moment où la plateforme a accepté le message et celui où le statut terminal s'est produit.
{
"event": "message.delivered",
"message_id": "01HZY8Q3M6",
"to": "+15551234567",
"status": "delivered",
"error": null,
"reason": null,
"submitted_at": "2026-07-19T09:15:22Z",
"done_at": "2026-07-19T09:15:25Z",
"sequence": 3
}L'énumération de statut de livraison
Standardiser les valeurs de statut est ce qui permet à un seul consommateur de gérer chaque opérateur, car les réponses réseau brutes varient énormément. Une énumération canonique les projette sur une poignée d'états à la sémantique claire : si l'état est terminal, et s'il est un succès. Les états intermédiaires (accepted, enroute) peuvent être supplantés par un événement ultérieur pour le même id de message, ce qui est précisément pourquoi les charges utiles portent une séquence ou un timestamp et pourquoi les consommateurs appliquent la règle d'auto-ordonnancement issue de la fiabilité des webhooks — un accepted tardif ne doit jamais écraser un delivered antérieur.
| status | Terminal | Signification |
|---|---|---|
| accepted | No | La plateforme a accepté le message pour livraison |
| enroute | No | Remis à l'opérateur, en attente d'un accusé |
| delivered | Oui | Remise au terminal confirmée |
| undelivered | Oui | L'opérateur n'a pas pu effectuer la livraison (voir erreur/raison) |
| expired | Oui | Période de validité expirée avant la livraison |
| rejected | Oui | Refusé (numéro invalide, expéditeur bloqué, filtre anti-spam) |
| unknown | Oui | L'opérateur n'a renvoyé aucun état final définitif |
Charge utile de message entrant (MO)
Un événement entrant porte le contenu du message plus le routage nécessaire pour répondre et corréler une conversation. Les champs critiques sont from (le MSISDN de l'abonné au format E.164), to (le numéro ou short/long code auquel il a écrit), et le texte ; à leurs côtés, un id de message pour le message entrant lui-même, un timestamp de réception, et — parce que le SMS entrant est soumis aux mêmes règles d'encodage et de segmentation que le sortant — l'encodage et, pour un message multipart, la référence de concaténation et les index de parts pour que le consommateur puisse réassembler le texte complet. Les événements entrants sont ce qui pilote les campagnes par mot-clé, les conversations bidirectionnelles et les flux de conformité STOP/HELP.
{
"event": "message.inbound",
"message_id": "01HZY8R7T0",
"from": "+15551234567",
"to": "44160",
"text": "STOP",
"encoding": "GSM7",
"received_at": "2026-07-19T09:20:11Z",
"concat": { "ref": null, "part": 1, "total": 1 }
}Taxonomie des types d'événements
Au-delà des DLR et MO, une plateforme émet des événements de cycle de vie et de compte, et un schéma de nommage cohérent — une chaîne pointée resource.action — permet à un consommateur de s'y abonner et de les router proprement. Les événements de statut de livraison sont des variations de message.<statut> ; l'événement entrant est message.inbound. Le regroupement par préfixe de ressource signifie qu'un consommateur peut faire correspondre message.* pour tout ce qui concerne un message et réserver d'autres préfixes aux événements de compte ou de numéro. Chaque événement devrait aussi porter un id d'événement stable (utilisé comme nonce de signature et clé de déduplication) et la chaîne de type, pour que le discriminant et la clé d'idempotence soient toujours présents.
| Type d'événement | Famille | Déclenché lorsque |
|---|---|---|
| message.accepted | Statut (DLR) | Message accepté pour livraison |
| message.delivered | Statut (DLR) | Livraison au téléphone confirmée |
| message.undelivered | Statut (DLR) | L'opérateur n'a pas pu remettre le message |
| message.expired | Statut (DLR) | Période de validité expirée |
| message.rejected | Statut (DLR) | Message refusé en amont |
| message.inbound | Entrant (MO) | Un abonné vous a envoyé un message |
Projeter un DLR HTTP sur un deliver_sm SMPP
Le callback de statut de livraison HTTP et l'accusé de livraison SMPP sont la même information sous deux encodages, et une plateforme qui fait le pont entre REST et SMPP traduit entre les deux. Sur SMPP, un accusé arrive sous forme de PDU deliver_sm dont l'esm_class le marque comme un accusé ; son champ short-message porte un accusé textuel avec les champs id, stat et err, et le TLV message_state porte l'état numérique. Le DLR HTTP les élève en JSON : le token stat SMPP se projette sur l'énumération de statut canonique, la valeur err se projette sur le champ error, et les heures submit/done de l'accusé se projettent sur submitted_at/done_at. Comprendre cette projection est ce qui permet à un seul chemin de code de gestion de livraison de servir les deux transports ; le format d'accusé SMPP et le PDU deliver_sm sont documentés en détail dans la référence SMPP.
| Champ de l'accusé SMPP | Champ DLR HTTP | Note |
|---|---|---|
| id (accusé) | message_id | Correspond au submit_sm / POST d'origine |
| stat (DELIVRD/UNDELIV/EXPIRED/REJECTD) | status | Le jeton correspond à l'énumération canonique |
| err | error | Code d'erreur opérateur/réseau |
| message_state TLV | status (valeur numérique sous-jacente) | État numérique SMPP correspondant au jeton |
| date de soumission / date d'achèvement | submitted_at / done_at | Horodatages de latence et de rapprochement |
Questions fréquemment posées
Que contient une charge utile de webhook de statut de livraison (DLR) ?
Le message_id attribué par le serveur qui la corrèle à votre envoi, un statut tiré d'une énumération canonique (accepted, enroute, delivered, undelivered, expired, rejected, unknown), un code d'erreur et une raison lisible par un humain pour les échecs, et des timestamps indiquant quand le message a été soumis et quand le statut terminal s'est produit.
En quoi un événement entrant (MO) diffère-t-il d'un DLR ?
Un DLR est le résultat asynchrone d'un message que vous avez envoyé. Un événement entrant (MO) est non sollicité — un message qu'un abonné a envoyé à votre numéro ou une réponse à une campagne — portant from, to, le texte, l'encodage et, pour les messages multipart, les champs de concaténation. Ils partagent transport et signature mais ont des schémas différents, si bien que les consommateurs bifurquent d'abord sur le type d'événement.
Pourquoi standardiser l'énumération de statut de livraison ?
Parce que les réponses opérateurs brutes varient énormément. Les projeter sur une petite énumération canonique à la sémantique claire de terminaison-et-succès permet à un seul consommateur de gérer chaque opérateur uniformément, et de décider à partir du seul statut s'il faut supprimer une mauvaise destination, réémettre un échec transitoire ou enregistrer une livraison confirmée.
Comment empêcher un « accepted » tardif d'écraser un « delivered » antérieur ?
Utilisez les champs d'auto-ordonnancement. Les charges utiles DLR portent un timestamp et souvent un numéro de séquence ; le consommateur les compare au dernier état enregistré pour cet id de message et écarte tout événement plus ancien que ce qu'il détient déjà, de sorte qu'un état intermédiaire hors ordre n'écrase jamais un état terminal.
Comment un DLR HTTP se projette-t-il sur un accusé deliver_sm SMPP ?
Ils portent la même information. Sur SMPP, l'accusé est un PDU deliver_sm marqué dans l'esm_class, avec les champs id, stat et err et un TLV message_state. Le DLR HTTP projette stat sur l'énumération de statut, err sur error, et les timestamps de l'accusé sur submitted_at/done_at — de sorte qu'un seul chemin de gestion de livraison peut servir les deux transports.
Quels champs permettent de réassembler un SMS entrant multipart ?
Les champs de concaténation : une référence qui lie les parts entre elles, l'index de part et le nombre total. Comme le SMS entrant obéit aux mêmes règles d'encodage et de segmentation que le sortant, un long message entrant arrive sous forme de plusieurs événements MO que le consommateur assemble dans l'ordre à l'aide de ces champs.
Spécifications sources
Les normes publiées sur lesquelles repose cette page. S'ouvre dans un nouvel onglet.