Unternehmenstelefonnummern

In diesem Dokument werden die WhatsApp Business-Telefonnummern, ihre Anforderungen, Verwaltungsanweisungen und Funktionen beschrieben.

Unternehmenstelefonnummern registrieren

Eine gültige Unternehmenstelefonnummer muss registriert werden, bevor sie zum Senden und Empfangen von Nachrichten über die Cloud API verwendet werden kann. Registrierte Nummern können weiterhin für alltägliche Zwecke wie Anrufe und SMS verwendet werden, nicht aber für den WhatsApp Messenger („WhatsApp“).

Telefonnummern, die bereits bei WhatsApp verwendet werden, können nicht registriert werden, es sei denn, sie werden vorher gelöscht. Wenn deine Telefonnummer bei WhatsApp gesperrt ist und du sie registrieren möchtest, muss die Sperrung zunächst im Rahmen des Widerspruchsverfahrens aufgehoben werden.

Wenn du die ersten Schritten in unserem Dokument abgeschlossen hast, wird automatisch eine Test-Unternehmenstelefonnummer für dich generiert und registriert.

Voraussetzungen

Zulässige Telefonnummern müssen folgende Anforderungen erfüllen:

• Du bist Inhaber*in der Nummer.
• Die Nummer verfügt über eine Landes- und Ortsvorwahl (Kurzcodes werden nicht unterstützt).
• Die Nummer kann Sprachanrufe oder SMS empfangen.
• Die Nummer sollte skalierte Funktionen haben.

Wenn du eine 1-800-Nummer registrierst, findest du weitere Informationen unter Registrieren von 1-800- und gebührenfreien Nummern.

Registrierungsmethoden

• App-Dashboard: Führe die in unserem Dokument Erste Schritte beschriebenen Schritte aus, falls noch nicht geschehen. Füge anschließend unter App Dashboard > WhatsApp > API Setup eine Telefonnummer hinzu.
• Meta Business Suite: Du kannst eine Unternehmenstelefonnummer registrieren, wenn du mit der Meta Business Suite ein WhatsApp-Unternehmenskonto erstellst.
• WhatsApp Manager: Weitere Informationen findest du in unserem Artikel So verbindest du deine Telefonnummer mit deinem WhatsApp-Unternehmenskonto im Hilfebereich.
• Embedded Signup: Wenn du mit einem Lösungspartner zusammenarbeitest, erhältst du einen Link zum Embedded Signup, über den du eine Telefonnummer registrieren kannst.

Status

Unternehmenstelefonnummern haben einen Status, der ihre Qualitätsbewertung und ihr aktuelles Nachrichtenlimit widerspiegelt. Unternehmenstelefonnummern müssen den Status „Verbunden“ haben, um Nachrichten über die API senden und empfangen zu können.

Status über WhatsApp Manager anzeigen

Der aktuelle Status deiner Unternehmenstelefonnummer wird in der Spalte Status im WhatsApp Manager unter Account tools > Phone numbers angezeigt.

Weitere Informationen zu Qualitätsbewertungen und Status im WhatsApp Manager findest du in unserem Hilfebereich im Artikel Infos zur Qualitätsbewertung deiner WhatsApp Business-Telefonnummer.

Status über API abrufen

Fordere das status-Feld deiner WhatsApp Business-Telefonnummer-ID an. Eine Liste der Statuswerte, die zurückgegeben werden können, und deren Bedeutung findest du in der Referenz zu GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>.

Beispielanfrage

curl 'https://graph.facebook.com/v24.0/106540352242922?fields=status' \
-H 'Authorization: Bearer EAAJB...'

Beispielantwort

{
  "status": "CONNECTED",
  "id": "106540352242922"
}

Display-Namen

Bei der Registrierung einer Unternehmenstelefonnummer musst du einen Display-Namen angeben. Der Display-Name erscheint im WhatsApp-Profil deiner Unternehmenstelefonnummer und kann unter bestimmten Bedingungen auch oben in Einzelchats und in der Chatliste erscheinen. Weitere Informationen zur Funktionsweise von Display-Namen findest du in unserem Dokument zu Display-Namen.

Unternehmensprofile

Ein Unternehmensprofil enthält zusätzliche Informationen zu deinem Unternehmen, wie z. B. Adresse, Website oder Beschreibung. Du kannst diese Informationen bei der Registrierung deiner Unternehmenstelefonnummer angeben. Weitere Informationen zur Funktionsweise von Unternehmensprofilen findest du in unserem Dokument Unternehmensprofile.

Status als offizielles Unternehmenskonto

Unternehmenstelefonnummern können den Status eines offiziellen Unternehmenskontos („OBA“) erhalten. OBA-Nummern sind in der Kontakteansicht neben ihrem Namen mit einem blauen Häkchen gekennzeichnet.

In unserem Dokument Offizielles Unternehmenskonto erfährst du, wie du den OBA-Status für eine Unternehmenstelefonnummer beantragen kannst.

Verifizierung in zwei Schritten

Du musst bei der Registrierung einer Unternehmenstelefonnummer eine PIN für die Verifizierung in zwei Schritten festlegen. Du benötigst deine PIN, wenn du deine PIN änderst oder deine Telefonnummer von der Plattform löschst.

PIN über den WhatsApp Manager ändern

Du benötigst deine aktuelle PIN, um deine PIN über den WhatsApp Manager zu ändern. So änderst du deine PIN:

1. Navigiere zu WhatsApp Manager > Account tools > Phone numbers.
2. Wähle deine Unternehmenstelefonnummer aus.
3. Klicke auf den Tab Two-step verification.
4. Klicke auf Change PIN und schließe den Vorgang ab.

Wenn du deine PIN nicht hast, kannst du sie über die API ändern.

PIN über die API ändern

Du kannst eine neue PIN über den Endpunkt POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> festlegen.

Beispielanfrage

curl 'https://graph.facebook.com/v24.0/106540352242922/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "pin": "150954"
}'

Beispielantwort

Bei Erfolg:

{
  "success": true
}

Deaktivieren der Verifizierung in zwei Schritten

Um die Verifizierung in zwei Schritten mit dem WhatsApp Manager zu deaktivieren, befolge die Schritte zum Ändern deiner PIN, klicke jedoch stattdessen beim letzten Schritt auf den Button Verifizierung in zwei Schritten deaktivieren. Eine E-Mail mit einem Link wird an die E-Mail-Adresse gesendet, die deinem Business-Portfolio zugeordnet ist. Verwende den Link, um die Verifizierung in zwei Schritten zu deaktivieren. Sobald du die Funktion deaktiviert hast, kannst du sie erneut aktivieren, indem du eine neue PIN festlegst.

Beachte, dass du die Verifizierung in zwei Schritten nicht über die API deaktivieren kannst.

1-800- und gebührenfreie Nummern

Du möchtest möglicherweise eine 1-800-Nummer oder eine andere gebührenfreie Nummern in der Plattform registrieren. Diese Nummern befinden sich üblicherweise hinter einem IVR-System (Interactive Voice Response), das für WhatsApp-Registrierungsanrufe nicht zugänglich ist. Telefonnummern, die sich hinter einem IVR-System befinden, können registriert werden. Sie müssen jedoch Anrufe von internationalen Nummern empfangen und unsere SMS-Nachricht oder unseren Sprachanruf an eine reale Person weiterleiten können.

So registrierst du eine Telefonnummer, die sich hinter einem IVR-System befindet:

1. WhatsApp teilt dir eine oder zwei Telefonnummern mit, von denen aus der Registrierungsanruf durchgeführt wird.
2. Erstelle eine Positivliste für diese Nummern. Wenn du für diese Nummern keine Positivliste erstellen kannst, füge die Telefonnummer zu deinem WhatsApp-Unternehmenskonto hinzu. Öffne außerdem ein Direct Support-Ticket, in dem du nach den Telefonnummern für den Registrierungsanruf fragst und die Telefonnummer angibst, die du registrieren möchtest.
3. Leite den Registrierungsanruf an eine*n Mitarbeiter*in oder eine Mailbox weiter, um den Registrierungscode zu erhalten.

Telefonnummern hinter einem IVR-System, die keine Registrierungsanrufe empfangen können, werden nicht unterstützt.

Obergrenze für registrierte Nummern

Neue Business-Portfolios sind zunächst auf zwei registrierte Unternehmenstelefonnummern begrenzt.

Falls dein Unternehmen verifiziert wird oder du ein Messaging-Limit von 2.000 erreicht hast, erhöhen wir das Limit automatisch auf 20. Nach der Erhöhung wird eine Meta Business Suite-Benachrichtigung gesendet, in der du über dein neues Limit informiert wirst. Außerdem wird ein business_capability_update-Webhook ausgelöst, wobei max_phone_numbers_per_business auf dein neues Limit festgelegt wird.

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

Beispielanfrage

curl -X POST 'https://graph.facebook.com/v24.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

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 Webhook zu eingehenden Nachrichten oder in Webhooks 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 Business-Telefonnummer > Einstellungen, um die Einstellung „Prüfung der Identitätsänderung“ zu aktivieren oder deaktivieren.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Post-Body

{
  "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/v24.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/v24.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... "
  }
}'

Webhooks

Bei eingehenden Nachrichten-Webhooks mit einem contacts-Objekt, wie etwa dem Textnachrichten-Webhook, wird der Hash des*der Kund*in der identity_key_hash-Eigenschaft zugewiesen.

In ausgehenden Nachrichten-Webhooks (Statusnachrichten-Webhooks) wird der Hash des*der Kund*in der Eigenschaft recipient_identity_key_hash im Objekt statuses zugewiesen.

Durchsatzrate abrufen

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

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Alle Telefonnummern abrufen

Um eine Liste aller Telefonnummern abzurufen, die mit einem WhatsApp-Unternehmenskonto verknüpft sind, sende eine GET-Anfrage an den Endpunkt WhatsApp Business Account Phone Numbers.

Telefonnummern können außerdem in auf- oder absteigender Reihenfolge nach last_onboarded_time sortiert werden. Dieser Wert basiert auf dem Zeitpunkt, zu dem eine Person die Freischaltung für Embedded Signup abgeschlossen hat. Wird kein Wert angegeben, erfolgt die Sortierung standardmäßig in absteigender Reihenfolge.

Anfragesyntax

curl -X GET "https://graph.facebook.com/<API_VERSION>/<WABA_ID>/phone_numbers?access_token=<ACCESS_TOKEN>" 

Bei Erfolg wird ein JSON-Objekt mit einer Liste aller Unternehmensnamen, Telefonnummern, Telefonnummern-IDs und Qualitätsbewertungen zu einem Unternehmen zurückgegeben. Die Ergebnisse werden nach dem Abschlussdatum des Embedded Signup in absteigender Reihenfolge sortiert. Dabei werden die zuletzt freigeschalteten zuerst aufgeführt.

Beispielantwort

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
      
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Anfragesyntax

curl -X GET "https://graph.facebook.com/<API_VERSION>/<WABA_ID>/phone_numbers?access_token=&lt;SYSTEM_USER_ACCESS_TOKEN>]&amp;sort=['last_onboarded_time_ascending']" 

Beispielantwort

Bei Erfolg wird ein JSON-Objekt mit einer Liste aller Unternehmensnamen, Telefonnummern, Telefonnummern-IDs und Qualitätsbewertungen zu einem Unternehmen zurückgegeben. Die Ergebnisse werden nach dem Abschlussdatum des Embedded Signup in aufsteigender Reihenfolge sortiert. Dabei werden die zuletzt freigeschalteten als letztes aufgeführt.

{
  "data": [
   {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    },
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"     
    }   
  ]
}

Telefonnummern filtern

Du kannst Telefonnummern abfragen und sie basierend auf ihrem account_mode filtern. Diese Filteroption wird derzeit in der Beta-Version getestet. Nicht alle Entwickler*innen haben Zugriff auf diese Option.

Parameter

Anfragesyntax

curl -i -X GET "https://graph.facebook.com/<API_VERSION>/<WABA_ID>/phone_numbers?filtering=[{"field":"account_mode","operator":"EQUAL","value":"SANDBOX"}]&access_token=<ACCESS_TOKEN> 

Beispielantwort

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "verified_name": "John’s Cake Shop",
      "quality_rating": "UNKNOWN",
    }
  ],
  "paging": {
	"cursors": {
		"before": "abcdefghij",
		"after": "klmnopqr"
	}
   }
}

Eine einzelne Telefonnummer abrufen

Um Informationen über eine Telefonnummer abzurufen, sende eine GET-Anfrage an den Endpunkt WhatsApp Business-Telefonnummer:

Anfragesyntax

GET https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>

Beispielanfrage

curl \
'https://graph.facebook.com/v15.0/105954558954427/' \
-H 'Authorization: Bearer EAAFl...'

Bei Erfolg wird ein JSON-Objekt mit dem Unternehmensnamen, der Telefonnummer, der Telefonnummern-ID und einer Qualitätsbewertung für die Telefonnummer zurückgegeben.

{
  "code_verification_status" : "VERIFIED",
  "display_phone_number" : "15555555555",
  "id" : "105954558954427",
  "quality_rating" : "GREEN",
  "verified_name" : "Support Number"
}

Status des Anzeigenamens abrufen (Beta)

Beziehe fields=name_status als Abfrageparameter ein, um den Status eines Anzeigenamens, der mit einer bestimmten Telefonnummer verknüpft ist, abzufragen. Dieses Feld befindet sich derzeit in der Beta-Phase und steht nicht allen Entwickler*innen zur Verfügung.

Beispielanfrage

curl \
'https://graph.facebook.com/v15.0/105954558954427?fields=name_status' \
-H 'Authorization: Bearer EAAFl...'

Beispielantwort

{
  "id" : "105954558954427",
  "name_status" : "AVAILABLE_WITHOUT_REVIEW"
}

Der name_status-Wert kann einer der folgenden sein:

• APPROVED: Der Name wurde genehmigt. Du kannst dein Zertifikat jetzt herunterladen.
• AVAILABLE_WITHOUT_REVIEW: Das Zertifikat für dieses Telefon ist verfügbar und der Anzeigename kann ohne Überprüfung verwendet werden.
• DECLINED: Der Name wurde nicht genehmigt. Du kannst dein Zertifikat nicht herunterladen.
• EXPIRED: Dein Zertifikat ist abgelaufen und du kannst es nicht mehr herunterladen.
• PENDING_REVIEW: Deine Namensanfrage wird geprüft. Du kannst dein Zertifikat nicht herunterladen.
• NONE: Es ist kein Zertifikat verfügbar.

Beachte, dass Zertifikate für sieben Tage gültig sind.

Unternehmenstelefonnummern löschen

Nur Admins des Business-Portfolios können Unternehmenstelefonnummern löschen. Außerdem können Telefonnummern, die in den letzten 30 Tagen für das Senden bezahlter Nachrichten verwendet wurden, nicht gelöscht werden.

Unternehmenstelefonnummern über den WhatsApp Manager löschen

Wenn deine Unternehmenstelefonnummer den Status „Verbunden“ hat, benötigst du zum Löschen deiner Telefonnummer deine PIN für die Verifizierung in zwei Schritten.

1. Rufe dein Business-Portfolio im WhatsApp Manager auf.
2. Wenn das Telefonnummern-Panel nicht automatisch geladen wird, navigiere zu Kontofunktionen (das Werkzeugkastensymbol) > Telefonnummern.
3. Klicke auf das Mülleimersymbol bei der Telefonnummer und schließe den Vorgang ab.

Wenn die Telefonnummer in den letzten 30 Tagen verwendet wurde, um bezahlte Nachrichten zu senden, wirst du zur Ansicht Insights weitergeleitet, auf der du das Datum der bezahlten Nachricht siehst, die zuletzt gesendet wurde. Du kannst die Telefonnummer 30 Tage nach diesem Datum löschen.

Unternehmenstelefonnummern über die API löschen

Unternehmenstelefonnummern können nicht über die API gelöscht werden.

Unternehmenstelefonnummern migrieren

Du kannst sowohl Telefonnummern von einem WhatsApp-Unternehmenskonto zu einem anderen migrieren als auch eine Nummer von der On-Premises API zur Cloud API migrieren.

Unterhaltungskomponenten

Du kannst nützliche Nachrichten-UI-Komponenten aktivieren, um WhatsApp-Benutzer*innen die Interaktion mit deinem Unternehmen zu erleichtern. Siehe Unterhaltungskomponenten.