Umgang mit WhatsApp-Benutzernamen und BSUIDs

Dieser Leitfaden führt Sie durch die Änderungen, die Sie an Ihrer Vonage Messages API-Integration vornehmen müssen, um WhatsApp-Benutzernamen und BSUIDs zu unterstützen.

Voraussetzungen

Eine aktive Vonage-Application, bei der die Funktion „Nachrichten“ aktiviert ist
Ein WhatsApp-Business-Account (WABA) und eine WhatsApp-Telefonnummer, die mit Meta und Vonage verknüpft ist
Für eingehende Nachrichten und Status-Callbacks konfigurierte Webhook-Endpunkte

Aktualisieren Sie Ihre Nachrichtenversandanfragen

Sie können Nachrichten nun zusätzlich zu oder anstelle einer Telefonnummer auch über eine BSUID versenden. Die to In diesem Feld können nun entweder eine Telefonnummer oder eine BSUID für WhatsApp-Empfänger eingegeben werden.

Nur an eine Telefonnummer senden (bisheriges Verhalten, unverändert):

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "14155550123", "from": "14155559876", "text": "Hello!" }'

Nur an eine BSUID senden:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "US.13491208655302741918", "from": "14155559876", "text": "Hello!" }'

Wichtig: Geben Sie bei der Verwendung einer BSUID stets den vollständigen Wert an – einschließlich Ländercode, Punkt und aller alphanumerischen Zeichen. Das Weglassen oder Ändern eines Teils der BSUID führt dazu, dass die Anfrage fehlschlägt.

Verarbeitung der aktualisierten Antwort auf die gesendete Nachricht

Die Antwort auf den Befehl „send message“ bleibt unverändert. Weitere Informationen finden Sie unter Spezifikation der „Send Message“-API.

Handler für den Status-Callback (Webhook) aktualisieren

Status-Callbacks für gesendete, zugestellte und gelesene ausgehende Nachrichten enthalten nun einen whatsapp.recipient Objekt und ein profile Objekt mit neuen Feldern.

Aktualisierte Nutzdaten für den Status-Callback:

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "read",
  "channel": "whatsapp",
  "profile": {
    "name": "John Smith",
    "username": "johnSmith"
  },
  "usage": { "currency": "EUR", "price": "0" },
  "whatsapp": {
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "conversation": {
      "id": "1234567890",
      "origin": { "type": "marketing" }
    }
  }
}

Neue und geänderte Felder:

Feld	Beschreibung
`profile.username`	Der WhatsApp-Benutzername des Nutzers, sofern er einen festgelegt hat. Wird bei „Gesendet“ weggelassen oder wenn der Nutzer keinen Benutzernamen hat.
`whatsapp.recipient.user_id`	Die BSUID des Benutzers. Ist bei den Status „zugestellt“ und „gelesen“ immer vorhanden.
`whatsapp.recipient.parent_user_id`	Die übergeordnete BSUID des Benutzers. Diese Angabe ist nur vorhanden, wenn Ihr Unternehmen übergeordnete BSUIDs aktiviert hat.
`whatsapp.recipient.wa_id`	Die Telefonnummer des Nutzers. Wird weggelassen, wenn die Nachricht an eine BSUID gesendet wurde und die Telefonnummer nicht angegeben werden kann.

Für failed Status-Callbacks, recipient_user_id wird weggelassen, wenn die Nachricht an eine Telefonnummer gesendet wurde.

Aktualisieren Sie Ihren Handler für eingehende Nachrichten (Webhook)

Webhooks für eingehende Nachrichten enthalten nun einen whatsapp.sender Objekt und eine aktualisierte profile Objekt.

Aktualisierte Nutzdaten für den Rückruf bei eingehenden Nachrichten:

Die from Das Feld enthält die Telefonnummer des Benutzers, sofern diese verfügbar ist. Ist die Telefonnummer nicht verfügbar, wird stattdessen die BSUID angezeigt.

Neue und geänderte Felder:

Feld	Beschreibung
`profile.username`	Der WhatsApp-Benutzername des Nutzers, sofern er einen festgelegt hat. Wird weggelassen, wenn der Nutzer keinen Benutzernamen hat.
`whatsapp.sender.user_id`	Die BSUID des Benutzers. Immer vorhanden.
`whatsapp.sender.parent_user_id`	Die übergeordnete BSUID des Benutzers. Diese Angabe ist nur vorhanden, wenn Ihr Unternehmen übergeordnete BSUIDs aktiviert hat.
`whatsapp.sender.wa_id`	Die Telefonnummer des Benutzers. Wird weggelassen, wenn der Benutzer einen Benutzernamen gewählt hat und die Telefonnummer gemäß den oben beschriebenen Bedingungen nicht angegeben werden kann.

Die Telefonnummer eines Benutzers anfordern (optional)

Wenn Ihre Integration die Telefonnummer eines Nutzers benötigt – beispielsweise zu Authentifizierungs- oder Verifizierungszwecken –, können Sie diese direkt im Chat abfragen. Dazu gibt es zwei Möglichkeiten: über eine vorab genehmigte Standardnachricht oder über einen interaktive Nachricht.

Option 1: Vorlagen-Nachricht mit einer Schaltfläche zur Anforderung von Kontaktdaten

Sie müssen zunächst eine WhatsApp-Vorlage erstellen und genehmigen lassen, die Folgendes enthält: REQUEST_CONTACT_INFO Schaltfläche über die WhatsApp Vorlagenverwaltung API. Sobald die Vorlage genehmigt wurde, senden Sie sie über die Vonage Messages API:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "template", "template": { "name": "YOUR_TEMPLATE_NAME", "language": { "policy": "deterministic", "code": "en" }, "components": [ { "type": "BODY", "parameters": [] }, { "type": "buttons", "buttons": [ { "type": "REQUEST_CONTACT_INFO", "text": "Share Contact Info" } ] } ] } } }'

Option 2: Interaktive Nachricht mit einer Schaltfläche zur Anforderung von Kontaktdaten

Sie können eine Telefonnummer auch innerhalb eines aktiven Chatfensters mithilfe einer interaktiven Nachricht anfordern, ohne dass dafür eine vorab genehmigte Vorlage erforderlich ist:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "interactive", "interactive": { "type": "request_contact_info", "body": { "text": "Please share your phone number with us to continue." }, "action": { "name": "request_contact_info" } } } }'

Weitere Informationen

WhatsApp-Benutzernamen und BSUIDs verstehen

Navigation