Rappels liés au statut WhatsApp

Lorsque vous envoyez un message WhatsApp à l'aide de la Messages API, Vonage se charge de la transmission rappels d'état vers l'URL de webhook que vous avez configurée chaque fois que le statut d'un message change — par exemple, lorsqu'il est envoyé, remis ou lu.

Vonage reçoit les mises à jour de statut de Meta (le fournisseur sous-jacent de WhatsApp) et les convertit dans un format de rappel harmonisé avant de les transmettre à votre application. Cela signifie que la charge utile reçue par votre webhook peut différer de la charge utile brute du webhook de Meta.

Pour obtenir une vue d'ensemble des callbacks d'état sur l'ensemble des canaux, consultez Messages API Callbacks d'état.

Rappels relatifs à l'état des messages

Vonage envoie une notification de statut à l'URL de votre webhook chaque fois qu'un message WhatsApp passe à un nouvel état. Les états suivants sont pris en charge :

Statut Description
submitted Vonage a reçu le message et l'a transmis à WhatsApp.
delivered Le message a été transmis à l'appareil du destinataire.
read Le destinataire a ouvert le message (cette fonctionnalité nécessite l'activation des accusés de lecture).
rejected Le message a été rejeté par Vonage ou WhatsApp. Un error L'objet est inclus dans la charge utile.
undeliverable Vonage n'a pas pu se connecter à WhatsApp pour envoyer le message.

Chargement utile du rappel d'état

L'exemple suivant présente l'ensemble complet des champs pouvant figurer dans une réponse de statut WhatsApp. Tous les champs ne sont pas nécessairement présents dans chaque réponse — par exemple, error n'est inclus que pour rejected ou undeliverable statuts, workflow n'est inclus que lorsque le message a été envoyé dans le cadre d'un workflow, et profile / whatsapp.recipient ne sont incluses que si elles sont disponibles sur WhatsApp :

{
  "to": "447700900001",
  "from": "447700900001",
  "channel": "whatsapp",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0"
  },
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "whatsapp": {
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "waba_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "conversation": {
      "id": "1234567890",
      "origin": {
        "type": "marketing"
      }
    }
  },
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "timestamp": "2025-02-03T12:14:25Z",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": "1000",
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  },
  "client_ref": "abc123",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

Pour obtenir la liste complète des champs d'état, consultez le Champs de rappel d'état section de la documentation de référence de la Messages API.

Rappels en cas d'erreur

Lorsqu'un message est rejeté ou ne peut être remis, la fonction de rappel inclut un error objet :

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "rejected",
  "channel": "whatsapp",
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1000",
    "title": 1000,
    "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
    "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
  }
}

Rappels pour les messages entrants

Lorsqu'un utilisateur de WhatsApp envoie un message à votre numéro WhatsApp Business, Vonage transfère ce message vers l'URL de votre webhook entrant.

Vous devez configurer une URL de webhook entrant dans votre Tableau de bord de l'API Vonage ou via l'API d'application pour recevoir des messages entrants.

Contenu du message entrant

Voici un exemple de rappel par SMS :

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "profile": {
    "name": "Jane Smith",
    "username": "janesmith123"
  },
  "context_status": "available",
  "context": {
    "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
    "message_from": "447700900000"
  },
  "provider_message": "Message delivered",
  "message_type": "text",
  "text": "Hello from Vonage!",
  "whatsapp": {
    "sender": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "referral": {
      "body": "Check out our new product offering",
      "headline": "New Products!",
      "source_id": "212731241638144",
      "source_type": "post",
      "source_url": "https://fb.me/2ZulEu42P",
      "media_type": "image",
      "image_url": "https://example.com/image.jpg",
      "video_url": "https://example.com/video.mp4",
      "thumbnail_url": "https://example.com/thumbnail.jpg",
      "ctwa_clid": "1234567890"
    }
  },
  "_self": {
    "href": "https://api-eu.vonage.com/v1/messages/aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
  }
}

Pour obtenir la liste complète des champs des messages entrants, consultez le Champs des messages entrants section de la documentation de référence de la Messages API.

Champs obsolètes

Les champs suivants devraient être obsolètes :

Champ d'application Notes
whatsapp.conversation Cette fonctionnalité sera obsolète à partir de la version 23.0 de l'API Webhooks, sauf pour les conversations via le point d'entrée gratuit.
pricing.billable Cette fonctionnalité sera obsolète dans une prochaine version. Utilisez whatsapp.pricing au lieu de cela.
usage.price Sera défini sur "0" à compter du 1er juillet 2025, dans le cadre du modèle de tarification à l'unité (PMP).

Plus d'informations

Messages API Callbacks d'état