Telefonnummern

In diesem Leitfaden wird erläutert, wie du deine Telefonnummer verifizierst und welche Formatierung für die Cloud API erforderlich ist.

Es gibt Kriterien dafür, welche Art von Telefonnummern du deinem WhatsApp Business Account (WABA) hinzufügen kannst. Weitere Informationen dazu findest du unter Telefonnummern.

Bei einigen der aufgeführten API-Aufrufe musst du die ID deiner Telefonnummer kennen. Unter Alle Telefonnummern abrufen erfährst du, wie du die mit deinem WABA verknüpften Telefonnummern abrufst. Die Antwort des API-Aufrufs enthält die IDs aller mit deinem WhatsApp Business Account verknüpften Telefonnummern. Speichere die ID für das Telefon, das du für /PHONE_NUMBER_ID-Aufrufe verwenden möchtest.

Telefonnummern verifizieren

Die Telefonnummer, die du zum Senden von Nachrichten an deine Kund*innen verwenden möchtest, musst du verifizieren. Telefonnummern müssen mithilfe eines Codes verifiziert werden, der per SMS/Sprachanruf gesendet wird. Der Verifizierungsprozess kann über die unten dargestellten Graph API-Aufrufe erfolgen.

Zur Verifizierung einer Telefonnummer mittels Graph API sende eine POST-Anfrage an PHONE_NUMBER_ID/request_code. Gib in deinem Aufruf die gewählte Verifizierungsmethode und Sprache an.

Parameter

Beispiel

Beispielanfrage:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

Nach dem API-Aufruf erhältst du den Verifizierungscode über die ausgewählte Methode. Füge den Code in eine POST-Anfrage an PHONE_NUMBER_ID/verify_code ein, um den Verifizierungsprozess abzuschließen.

Parameter

Beispiel

Beispielanfrage:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

Eine erfolgreiche Antwort sieht wie folgt aus:

{
  "success": true
}

Prüfung der Identitätsänderung

Du möchtest möglicherweise, dass wir die Identität eines*einer Kund*in überprüfen, bevor wir deine Nachricht an ihn*sie übermitteln. Aktiviere hierzu die Einstellung „Prüfung der Identitätsänderung“ für deine Unternehmenstelefonnummer.

Wenn ein*e Kund*in eine Aktion in WhatsApp ausführt, die wir als Identitätsänderung identifizieren, erstellen wir einen neuen Identitäts-Hash für den*die Nutzer*in. Indem du die Einstellung „Prüfung der Identitätsänderung“ für deine Unternehmenstelefonnummer aktivierst, erhältst du diesen Hast immer, wenn du eine Nachricht an den*die Kund*in sendest. Sobald diese Einstellung aktiviert ist, schließen wir, immer wenn du eine Nachricht an den*die Kund*in ohne Identitäts-Hash sendest oder der*die Kund*in eine Nachricht an dich sendet, seinen*ihren Hash in einen Webhook zu einer eingehenden Nachricht oder in den Webhook zum Zustellungsstatus ein. Du kannst diesen Hash dann abrufen und zu späteren Verwendung speichern.

Um den Hash zu verwenden, schließe ihn in Anfragen zum Senden einer Nachricht ein. Wir nehmen den Hash in die Anfrage an den aktuellen Hash des*der Kund*in auf. Wenn die Hashes übereinstimmen, wird die Nachricht gesendet und zugestellt. Wenn keine Übereinstimmung besteht, bedeutet dies, dass der*die Kund*in seine*ihre Identität gewechselt hast, seit du ihm*ihr zuletzt eine Nachricht gesendet hast und wir werden die Nachricht nicht zustellen. Stattdessen erhältst du einen Webhook zum Nachrichtenstatus, der den Fehlercode 137000 enthält, um dich über das Fehlschlagen und die fehlende Übereinstimmung zu informieren.

Wenn du einen Webhook zu einem nicht übereinstimmenden Hash erhältst, ist anzunehmen, dass die Telefonnummer des*der Kund*in nicht länger als vertrauenswürdig angesehen werden kann. Um die Vertrauenswürdigkeit zu prüfen, verifiziere die Identität des*der Kund*in über einen anderen Kanal als WhatsApp. Sobald du die Vertrauenswürdigkeit überprüft hast, sende die fehlgeschlagene Nachricht ohne Hash erneut an die neue Identität (falls zutreffend). Speichere dann den neuen Hash des*der Kund*in, der im Webhook zum Zustellungsstatus der Nachricht enthalten ist.

Anfragesyntax

Sende eine POST-Anfrage an den Endpunkt WhatsApp-Unternehmenstelefonnummer > Einstellungen, um die Einstellung „Prüfung der Identitätsänderung“ zu aktivieren oder deaktivieren.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Anfrageinhalt

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

Lege <ENABLE_IDENTITY_KEY_CHECK> auf true fest, um die Prüfung der Identitätsänderung zu aktivieren oder auf false, um sie zu deaktivieren.

Beispielanfrage zum Aktivieren

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

Beispielantwort zum Aktivieren

{
  "success": true
}

Beispiel für gesendete Nachricht mit Prüfung

Diese Beispielnachricht würde nur zugestellt werden, wenn der Hash-Wert recipient_identity_key_hash mit dem aktuellen Hash des*der Kund*in übereinstimmt.

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

Beispiel für eingehende Nachricht mit Prüfung

In Webhooks zu eingehenden Nachrichten wird der Hash des*der Kund*in der Eigenschaft identity_key_hash zugewiesen.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Beispiel für Webhook zum Zustellungsstatus

In Webhooks zum Zustellungsstatus wird der Hash des*der Kund*in der Eigenschaft recipient_identity_key_hash zugewiesen.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Beispiel für Webhook zum Zustellungsstatus „Fehlgeschlagen“

In Webhooks zum Zustellungsstatus wird der Hash des*der Kund*in der Eigenschaft recipient_identity_key_hash zugewiesen.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Durchsatzrate abrufen

Verwende den WhatsApp-Unternehmenstelefonnummer-Endpunkt, um die aktuelle Durchsatzrate einer Telefonnummer abzurufen:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput