Messages API Callbacks d'état

L'API Messages envoie des rappels d'état à l'URL de votre webhook pour vous informer chaque fois qu'un événement modifie l'état d'un message - par exemple, lorsqu'il est soumis, délivré ou rejeté.

Ces rappels offrent une visibilité cohérente du cycle de vie des messages sur tous les canaux pris en charge, notamment SMS, MMS, RCSet des applications : WhatsApp, Viberet Facebook Messenger.

Chaque fois que l'état d'un message change, l'API Messages envoie un rappel d'état à votre webhook configuré.
Ce rappel comprend des informations clés telles que l'UUID du message, le canal, l'horodatage, l'état de livraison et, le cas échéant, les métadonnées relatives au prix et au réseau.

Les différents canaux soutiennent des événements et des niveaux d'information différents. Par exemple :

Statuts du rappel

Rappels de lecture d'état

Pour les canaux OTT tels que WhatsApp et Viber, l'API Messages peut envoyer un read lorsque le fournisseur indique que l'utilisateur final a lu le message sur son appareil.

Rappels de l'état de soumission

Ce statut signifie que Messages API a transmis un message à un fournisseur de services de messagerie.

Rappels de l'état non livrable

Cet état signifie que Messages API n'a pas pu se connecter au fournisseur de messagerie. Cela peut être dû à une panne du fournisseur de messagerie ou à un autre incident.

Rappels d'état rejetés

Un message peut être rejeté pour plusieurs raisons :

• Messages API ne peut pas traiter le message (par exemple, paramètres non valides ou support non pris en charge).
• Le fournisseur rejette le message - par exemple, envoi de MMS vers un pays non pris en charge.
• Le temps de vie (TTL) du message expire avant qu'il ne puisse être délivré.

Dans ces cas, un rejected est envoyé avec un objet d'erreur décrivant l'échec.

Exemples de rappels

SMS (message en plusieurs parties)

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2023-05-01T14:00:00.000Z",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "string",
  "channel": "sms",
  "destination": {
    "network_code": "12345"
  },
  "sms": {
    "total_count": "2"
  }
}

RCS (Rejected Request with SMS Failover)

{
  "message_uuid": "001",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:00.000Z",
  "status": "rejected",
  "channel": "rcs",
  "destination": {
    "network_code": "12345"
  },
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1260",
    "title": 1260,
    "detail": "Destination unreachable - The message could not be delivered to the phone number.",
    "instance": "abc102"
  },
  "workflow": {
    "id": "1001",
    "item_number": "1",
    "items_total": "2"
  }
}

Codes de réseau

L'API Messages comprend une fonction network_code dans les rappels pour identifier l'opérateur qui traite le message. Les codes de réseau sont des combinaisons de codes de pays (MCC) et de codes de réseau mobile (MNC). Ils s'appliquent aux SMS, RCS et MMS et représentent les données les plus précises disponibles au moment de l'événement de rappel d'état.