WhatsApp-Status-Callbacks
Wenn Sie eine WhatsApp-Nachricht über die Vonage Messages API versenden, stellt Vonage Folgendes bereit: Statusrückrufe an die von Ihnen konfigurierte Webhook-URL, sobald sich der Status einer Nachricht ändert – beispielsweise wenn sie gesendet, zugestellt oder gelesen wird.
Vonage empfängt Statusmeldungen von Meta (dem Betreiber von WhatsApp) und wandelt diese in ein einheitliches Callback-Format um, bevor sie an Ihre Anwendung weitergeleitet werden. Das bedeutet, dass sich die von Ihrem Webhook empfangenen Daten möglicherweise von den Rohdaten des Meta-Webhooks unterscheiden.
Einen allgemeinen Überblick über Status-Callbacks für alle Kanäle finden Sie unter Messages API-Statusrückrufe.
Rückrufe zum Nachrichtenstatus
Vonage sendet einen Status-Callback an Ihre Webhook-URL, sobald eine WhatsApp-Nachricht in einen neuen Status wechselt. Folgende Status werden unterstützt:
| Status | Beschreibung |
|---|---|
submitted |
Vonage hat die Nachricht empfangen und an WhatsApp weitergeleitet. |
delivered |
Die Nachricht wurde an das Gerät des Empfängers übermittelt. |
read |
Der Empfänger hat die Nachricht geöffnet (dazu müssen Lesebestätigungen aktiviert sein). |
rejected |
Die Nachricht wurde von Vonage oder WhatsApp abgelehnt. Eine error Das Objekt ist in der Nutzlast enthalten. |
undeliverable |
Vonage konnte keine Verbindung zu WhatsApp herstellen, um die Nachricht zu übermitteln. |
Status-Callback-Nutzdaten
Das folgende Beispiel zeigt alle Felder, die in einem WhatsApp-Status-Callback vorkommen können. Nicht jedes Feld ist in jedem Callback vorhanden – zum Beispiel, error ist nur enthalten für rejected oder undeliverable Status, workflow wird nur dann einbezogen, wenn die Nachricht im Rahmen eines Workflows gesendet wurde, und profile / whatsapp.recipient werden nur dann einbezogen, wenn sie von WhatsApp bereitgestellt werden:
{
"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"
}
}
Eine vollständige Liste der Statusfelder finden Sie unter Felder für Status-Callbacks Abschnitt der Referenz zur Messages API.
Fehler-Callbacks
Wenn eine Nachricht abgelehnt wird oder nicht zugestellt werden kann, enthält der Callback einen error Objekt:
{
"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"
}
}
Rückrufe bei eingehenden Nachrichten
Wenn ein WhatsApp-Nutzer eine Nachricht an Ihre WhatsApp Business-Nummer sendet, leitet Vonage die Nachricht an Ihre Webhook-URL für eingehende Nachrichten weiter.
Sie müssen eine URL für eingehende Webhooks in Ihrer Vonage API Dashboard oder über die Applications-API, um eingehende Nachrichten zu empfangen.
Nutzdaten der eingehenden Nachricht
Im Folgenden finden Sie ein Beispiel für einen Rückruf bei einem eingehenden SMS-Anruf:
{
"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"
}
}
Eine vollständige Liste der Felder für eingehende Nachrichten finden Sie unter Felder für eingehende Nachrichten Abschnitt der Referenz zur Messages API.
Veraltete Felder
Die folgenden Felder sollen als veraltet markiert werden:
| Feld | Anmerkungen |
|---|---|
whatsapp.conversation |
Wird ab Webhooks-API-Version 23.0 und höher nicht mehr unterstützt, mit Ausnahme von Konversationen über kostenlose Einstiegspunkte. |
pricing.billable |
Wird in einer zukünftigen Version als veraltet markiert. Verwenden Sie whatsapp.pricing stattdessen. |
usage.price |
Wird auf "0" ab dem 1. Juli 2025 im Rahmen des Per-Message-Pricing-Modells (PMP). |