Cloud API

WhatsApp Business Platform > Cloud API > Leitfäden

Migration von Cloud API zu On-Premises API

Wir stellen die On-Premises API ein. Weitere Informationen und wie du auf unsere Cloud API der nächsten Generation migrieren kannst, findest du in unserem Dokument zur Einstellung der On-Premises API.

In diesem Dokument wird erläutert, wie du Unternehmenstelefonnummern von der Cloud API zur On-Premises API migrierst. Mehr über die Migration von der On-Premises API zur Cloud API erfährst du unter Migration von der On-Premises API zur Cloud API..

Beachte, dass die Migration einer Unternehmenstelefonnummer von einer API zu einer anderen nicht dasselbe ist wie die Migration einer Nummer von einem WhatsApp-Unternehmenskonto (WABA) zu einem anderen.

Die Migration hat KEINE Auswirkungen auf Folgendes:

  • den Anzeigenamen, den Verifizierungsstatus oder die Qualitätsbewertung der Unternehmenstelefonnummer
  • Vorlagen, die von der Unternehmenstelefonnummer verwendet werden, oder deren Status
  • das Eigentums-WABA, seinen Status als offizielles Unternehmenskonto oder sein Nachrichtenlimit

Beachte bei der Migration allerdings alle API-Unterschiede und ergreife eventuell erforderliche Maßnahmen, bevor du die hier beschriebenen Migrationsschritte ausführst.

Best Practices

Wenn du weißt, dass keine Probleme durch API-Unterschiede in deiner App entstehen, solltest du zunächst eine Unternehmenstelefonnummer mit geringem Volumen migrieren und sicherstellen, dass alle gewünschten Funktionen mit der On-Premises API ordnungsgemäß funktionieren. Anschließend kannst du weitere Nummern migrieren.

Wir empfehlen dir außerdem, die Migration durchzuführen, wenn der Traffic zu deiner On-Premises API-Bereitstellung gering ist.

API-Unterschiede

Berücksichtige diese Unterschiede und behebe eventuelle Probleme, bevor du mit der Migration beginnst.

Webhooks

Payload-Strukturen der Cloud API- und Business Management API-Webhooks unterscheiden sich von denen der On-Premises API. Wir empfehlen die, einen neuen Webhook-Endpunkt zu erstellen, der ausschließlich On-Premises API-Webhooks bearbeiten kann.

Die folgenden Dokumente helfen dir dabei, die Nutzlastunterschiede zu verstehen:

Nach der Migration zur On-Premises API werden die Cloud API-Webhooks der Unternehmenstelefonnummer nicht mehr zugestellt. Stattdessen werden jetzt On-Premises API-Webhooks zugestellt.

Medien

Medien-IDs für alle in die Cloud API hochgeladenen Medien können nicht beim Senden von Nachrichten mit der On-Premises API verwendet werden. Du musst also entweder Medien mit der On-Premises API erneut hochladen, um neue Medien-IDs zu generieren, oder Medien-URLs verwenden, wenn die Medien auf einem öffentlichen Server gehostet werden. Siehe Mediennachrichten senden.

Fehlercodes

Fehlercodes der Cloud API und Business Management API unterscheiden sich von denen der On-Premises API. Mehr dazu erfährst du in den folgenden Dokumenten:

Push-to-Talk-Nachrichten

Die On-Premises API identifiziert Push-to-Talk-Nachrichten (PTT-Nachrichten) in Webhooks, wenn du messages.type auf voice setzt. Die Cloud API identifiziert PTT-Nachrichten aber durch Setzen von messages.audio.voice auf true.

Ausfallzeit

Die Ausfallzeit beginnt, sobald du den Registrierungsschritt (Schritt 3) ausgeführt hast, und sollte nur wenige Sekunden dauern. Während dieser Zeit werden Nachrichten, die WhatsApp-Benutzer*innen an die Nummer senden, ohne Ankündigung gelöscht.

Wir empfehlen dir dringend, die Migration während einer Zeit mit geringer Aktivität für die Nummer durchzuführen, um die Auswirkungen der Ausfallzeit zu minimieren.

Schritt 1: On-Premises API integrieren

Da du eine Unternehmenstelefonnummer zu On-Premises API migrierst, musst du sicherstellen, dass deine App deinen On-Premises API-Client erfolgreich nutzen kann und dass das WhatsApp-Unternehmenskonto, das mit der Unternehmenstelefonnummer verbunden ist, Webhooks korrekt konfiguriert hat.

Schritt 2: Die Migration vorbereiten

Wir empfehlen dir, während der Migration keine Nachrichten zu versenden.

Der WhatsApp Business On-Premises API-Client weist bestimmte Netzwerkanforderungen für die Verbindung mit den WhatsApp-Servern auf. Lies dir Dein Netzwerk einrichten und debuggen durch, um sicherzugehen, dass die Vorbereitung abgeschlossen ist.

Schritt 3: API-Client registrieren

Registriere die Unternehmenstelefonnummer auf deinem On-Premises API-Client. Rufe dazu den /account-Endpunkt auf:

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Die empfangene Antwort zeigt an, ob der Registrierungsvorgang beendet oder ein weiterer Schritt notwendig ist. Wenn der Vorgang erfolgreich ist, erhältst du einen der folgenden HTTP-Statuscodes: Befolge die Anweisungen für die empfangene Antwort:

  • 201 Created – Das Konto ist bereits vorhanden. Du bist bereits registriert, brauchst also nichts mehr zu tun.
  • 202 Accepted – Das Konto ist nicht vorhanden. Prüfe abhängig von der in der Anforderung gewählten Methode, ob der Registrierungscode per SMS oder Sprachanruf übermittelt wurde. Die Antwort enthält eine Payload mit dem vname, der aus dem Parameter cert decodiert wurde. So kannst du erkennen, ob der richtige Display-Name verwendet wird. Wenn dies der richtige Name ist, schließt du die Registrierung wie unter Abschließen der Kontoregistrierung beschrieben ab.

Hier findest du alle verfügbaren Felder für diesen Endpunkt.

Nach Abschluss der Registrierung ist es der On-Premises API-Client, der Nachrichten erhält.

Schritt 4: Shards festlegen

Sobald dein Client registriert ist, kannst du bei Bedarf Shards festlegen.

Schritt 5: Mit dem Senden von Nachrichten beginnen

Du kannst jetzt Nachrichten an deine Kund*innen senden. In den Leitfäden Nachrichten senden findest du weitere Informationen.