Erste Schritte für Lösungspartner

In diesem Leitfaden werden die Schritte beschrieben, die Lösungspartner durchführen müssen, um ihren Kund*innen die Cloud API anzubieten. Es gibt im Wesentlichen vier Phasen:

1. Vorbereitung und Planung
2. Einrichtung von Assets
3. Vertragsunterzeichnung
4. Integrationsentwicklung

Wenn du fertig bist, solltest du du dich mit monatlichen Updates auf dem Laufenden halten.

Vorbereitung und Planung

Dokumentation lesen

Bevor du beginnst, solltest du dir unsere Entwicklungsdokumentation und unsere Postman-Sammlung durchlesen. Darin wird erklärt, wie die Cloud API funktioniert und wie man mit der Migration von Zahlen beginnt.

Freischaltung und Migration planen

Du musst neue Kund*innen über Embedded Signup für die Cloud API freischalten. Integriere und starte Embedded Signup, falls du das noch nicht getan hast. Embedded Signup ist der schnellste und einfachste Weg, um Kund*innen zu registrieren, sodass sie in weniger als fünf Minuten mit dem Versand von Nachrichten beginnen können.

Überlege dir als Nächstes, welche Kund*innen du zuerst zur Cloud API migrieren möchtest. Generell empfehlen wir, alle deine Kund*innen von der On-Premises auf die Cloud API zu migrieren, aber die individuellen Bedürfnisse der Kund*innen können variieren. Berücksichtige bei der Entscheidung, welche Kund*innen migriert werden sollen, Folgendes:

Sobald du weißt, wer migriert werden soll, kannst du einen Migrations- und Zeitplan erstellen.

Denke bei der Erstellung deines Plans daran, dein System für zwei Szenarien zu entwerfen: Onboarding neuer Kunden und Migration bestehender Kunden von On-Premises zu Cloud API. Für das Migrationsszenario solltest du Pläne für die Sicherung deiner aktuellen lokalen Instanz und die Migration dieser Zahlen zur Cloud API einschließen.

Kommunikation mit Kund*innen planen

Zunächst musst du entscheiden, ob du bestehende Kund*innen über die Migration informieren möchtest. Anschließend solltest du klären, ob du eine Dokumentation erstellen oder aktualisieren musst, um die Einrichtung der Cloud API zu unterstützen.

Preisentscheidungen treffen

Da die Hosting-Kosten für die Cloud API von Meta übernommen werden, solltest du entscheiden, ob du deine Preise entsprechend anpassen möchtest.

Einrichtung von Assets

Um die Cloud API zu verwenden, benötigen Lösungspartner die folgenden Assets:

Vertragsunterzeichnung

Nutzungsbedingungen akzeptieren

Um Zugriff auf die WhatsApp Business Messaging Cloud API zu erhalten, musst du zunächst im Namen deines Unternehmens die Nutzungsbedingungen der WhatsApp Business Platform akzeptieren.

Navigiere hierzu zum WhatsApp Manager und stimme den Nutzungsbedingungen im Informationsbanner zu.

Als bestehender Beta-Partner der Cloud API hast du eine Frist von 90 Tagen. Das bedeutet, du musst die Nutzungsbedingungen bis zum 5. Juli 2022 akzeptieren, sonst erlischt dein Zugriff.

Alle Unternehmen, die neu bei der Cloud API sind, einschließlich der Unternehmen, die von der On-Premises API migrieren, müssen die Nutzungsbedingungen akzeptieren, bevor sie die Cloud API verwenden können. Solange die Nutzungsbedingungen nicht akzeptiert wurden, schlagen Registrierungsaufrufe fehl.

Integrationsentwicklung

Schritt 1: Systembenutzer-Zugriffsschlüssel abrufen

Graph API-Aufrufe verwenden Zugriffsschlüssel für die Authentifizierung. Weitere Informationen findest du unter Zugriffsschlüssel. Zum Generieren deines Schlüssels solltest du den Systembenutzer verwenden.

So generierst du einen Systembenutzer-Zugriffsschlüssel:

1. Gehe zu Business Manager > Unternehmenseinstellungen > Benutzer > Systembenutzer, um den von dir erstellten Systembenutzer anzuzeigen.
2. Klicke auf diesen Benutzer und wähle Assets hinzufügen aus. Durch diese Aktion wird ein neues Fenster geöffnet.
3. Wähle unter Asset-Typ auswählen im linken Seitenbereich Apps aus. Wähle unter Assets auswählen die Meta-App aus, die du verwenden möchtest (deine App muss über die korrekten Berechtigungen verfügen). Aktiviere für diese App App entwickeln.
4. Wähle Änderungen speichern aus, um deine Einstellungen zu speichern und zur Hauptseite „Systembenutzer“ zurückzukehren.
5. Jetzt kannst du deinen Schlüssel erstellen. Klicke auf der Hauptseite „Systembenutzer“ auf Schlüssel erstellen und wähle deine Meta-App aus. Nachdem du die App ausgewählt hast, siehst du eine Liste der verfügbaren Berechtigungen. Wähle whatsapp_business_management und whatsapp_business_messaging. Klicke auf Schlüssel erstellen.
6. Es neues Fenster mit deinem Systembenutzer, der zugewiesenen App und dem Zugriffsschlüssel wird geöffnet. Speichere deinen Schlüssel.
7. Optional kannst du auf deinen Schlüssel klicken und den Token Debugger anzeigen. Im Debugger sollten die beiden Berechtigungen angezeigt werden, über die du verfügst. Du kannst deinen Schlüssel auch direkt in den Zugriffsschlüssel-Debugger einfügen.

Schritt 2: Webhooks einrichten

Durch die Einrichtung von Webhooks erhältst du HTTP-Benachrichtigungen in Echtzeit von der WhatsApp Business Platform. Das bedeutet, du wirst benachrichtigt, wenn du beispielsweise eine Nachricht von einem*einer Kund*in erhältst oder Änderungen an deinem WhatsApp-Unternehmenskonto (WABA) vorgenommen werden.

Zum Einrichten deines Webhooks musst du einen mit dem Internet verbundenen Webserver mit einer URL, die die Anforderungen von Meta und WhatsApp erfüllt, erstellen. Anweisungen hierzu findest du unter Einen Endpunkt erstellen. Wenn du für Testzwecke einen Endpunkt benötigst, kannst du einen Test-Webhook-Endpunkt generieren.

App-Einrichtung

Sobald der Endpunkt bereit ist, konfiguriere ihn für die Verwendung mit deiner Meta-App:

Für jede deiner Anwendungen musst du nur ein einziges Mal Webhooks einrichten. Du kannst denselben Webhook verwenden, um verschiedene Eventtypen von mehreren WhatsApp-Unternehmenskonten zu empfangen. Weitere Informationen findest du im Abschnitt „Webhooks“.

Schritt 3: Dein WABA abonnieren

Abonniere deine App, um sicherzustellen, dass du Benachrichtigungen für den richtigen Account erhältst:

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Wenn du die nachfolgende Antwort erhältst, werden alle Webhook-Events für die Telefonnummern in diesem Account an den von dir konfigurierten Webhooks-Endpunkt gesendet.

{
  "success": true
}

Schritt 4: ID der Telefonnummer abrufen

Damit du Nachrichten senden kannst, musst du die Telefonnummer, die du verwenden möchtest, registrieren. Es handelt sich hierbei um die Unternehmenstelefonnummer, die im Abschnitt Bevor du beginnst erwähnt wurde.

Bevor du mit der Registrierung fortfahren kannst, musst du die ID dieser Telefonnummer ermitteln. Führe den folgenden API-Aufruf aus, um die ID deiner Telefonnummer anzurufen:

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Wenn der Aufruf erfolgreich ist, enthält die Antwort alle Telefonnummern, die mit deinem WABA verknüpft sind:

{
  "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"
    }
  ]
}

Speichere die ID der Telefonnummer, die du registrieren möchtest. Weitere Informationen über diesen Endpunkt findest du unter Telefonnummern lesen.

Ausnahme bei Migration

Schritt 5: Telefonnummer registrieren

Mit der ID der Telefonnummer kannst du diese registrieren. Im Registrierungs-API-Aufruf führst du zwei Aktionen gleichzeitig aus:

1. Registrieren des Telefons
2. Aktivieren der Verifizierung in zwei Schritten durch das Festlegen eines sechsstelligen Registrierungscodes – diesen Code musst du deinerseits festlegen. Speichere diesen Code und bewahre ihn auf, da er später abgefragt werden kann.

Die Einrichtung der zweistufigen Authentifizierung ist eine Voraussetzung für die Verwendung der Cloud API. Wenn du sie nicht einrichtest, wird eine Onboarding-Fehlermeldung angezeigt:

Beispielanfrage:

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

Beispielantwort:

{
  "success": true
}

Benutzer mit eingebetteter Anmeldung

Schritt 6: Eine Nachricht von der Verbraucher-App empfangen

Sobald teilnehmende Kund*innen eine Nachricht an dein Unternehmen senden, öffnet sich ein 24-stündiges Zeitfenster, in dem du ihnen kostenlose Nachrichten senden kannst. Dieses Zeitfenster wird als Kundenservicefenster bezeichnet. Zu Testzwecken aktivieren wir dieses Fenster, damit du so viele Nachrichten senden kannst, wie du möchtest.

Sende von einer persönlichen WhatsApp iOS-/Android-App aus eine Nachricht an die Telefonnummer, die du gerade registriert hast. Sobald die Nachricht gesendet wurde, solltest du eine eingehende Nachricht an deinem Webhook empfangen, die eine Benachrichtigung im folgenden Format enthält.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

Schritt 7: Testnachricht senden

Sobald du das Kundenservicefenster aktiviert hast, kannst du eine Testnachricht an die Verbrauchernummer schicken, die du im vorherigen Schritt verwendet hast. Tätige hierfür den folgenden API-Aufruf:

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

Wenn dein Aufruf erfolgreich ist, enthält deine Antwort eine Nachrichten-ID. Verwende diese ID, um den Fortschritt deiner Nachrichten über Webhooks nachzuverfolgen. Die maximale Länge der ID beträgt 128 Zeichen.

Beispielantwort:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Monatliche Updates erhalten

Wir veröffentlichen Cloud API-Updates jeden erst Dienstag im Monat. Diese enthalten neue Features und Verbesserungen. Du brauchst nichts tun, um die neue Features verwenden zu können, da die Cloud API automatisch aktualisiert wird.

FAQs

Allgemeine FAQs

FAQs zur technischen Implementierung

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

Permalink

FAQs zu Datenschutz und Sicherheit

FAQs zur Compliance