WhatsApp Hosted Embedded Sign-up Flow für Tech-Partner

WhatsApp Hosted Embedded Sign-up Flow ist eine White-Label Onboarding UI. Es ermöglicht Vonage Partnern, ihre Kunden in WhatsApp Business Accounts einzubinden, ohne dass sie ihren eigenen Embedded Sign-up Flow erstellen, konfigurieren oder hosten müssen.

Voraussetzungen

Um die eingebettete Anmeldelösung nutzen zu können, müssen Vonage Partner die folgenden Voraussetzungen erfüllen:

  • Registrieren Sie sich bei Meta als Technologieanbieter
  • Eine Meta-App live auf dem App-Dashboard haben
  • Sie müssen über "Full Control"- oder Admin-Rechte in dem Geschäftsportfolio verfügen, in das eine WABA- oder WhatsApp-Nummer eingefügt werden soll.
  • Sie haben eine Lösungsanfrage an Vonage gestellt, die Anfrage wurde angenommen, und Sie haben eine Lösungs-ID erhalten.

Wenn Sie Fragen zu einer der oben genannten Voraussetzungen haben oder Unterstützung benötigen, wenden Sie sich bitte an Ihren Vonage Account Manager.

Prozessablauf

Der Prozessablauf für die WhatsApp Hosted Embedded Anmeldung ist wie folgt:

  1. Der Vonage Partner generiert eine eingebettete Anmelde-URL
  2. Der Partner kann die URL an seine Kunden weitergeben (z. B. per E-Mail oder SMS oder durch Einbettung der URL auf seiner eigenen Webseite)
  3. Die URL leitet den Kunden zu einem von Vonage gehosteten, eingebetteten Anmeldevorgang, über den die Registrierung eines WhatsApp Business Accounts (WABA) oder einer WhatsApp Numbers abgeschlossen werden kann.
  4. Der Kunde schließt den Einführungsprozess mithilfe des eingebetteten Anmeldevorgangs ab

Hinweis: Die An- und Abmeldeversuche für jede WhatsApp Number sind begrenzt (10 Versuche pro Number pro Woche).

Generieren einer eingebetteten Anmelde-URL

Eine eingebettete Anmelde-URL kann durch eine POST-Anfrage an die URL-Endpunkt für Hosted ES Flow generieren der Kanalmanager-API.

Hinweis: Die Kanalmanager-API befindet sich derzeit im Beta-Status.

Die Authentifizierung kann über Basic Auth oder Bearer Token (JWT) Auth erfolgen.

Der Anfragekörper sollte ein JSON-Objekt enthalten, das mindestens eine solution_id Eigenschaft, deren Wert die von Vonage bereitgestellte Lösungs-ID ist (siehe Voraussetzungen).

Der Körper kann auch eine api_key um den Vonage Sub-Account des Kunden zu identifizieren, für den der Partner die URL erstellen möchte (wenn diese Eigenschaft weggelassen wird, wird der Haupt-API-Schlüssel für den primären Vonage Account verwendet).

A ttl kann auch ein Zeitlimit für die Gültigkeit der generierten URL festgelegt werden (Maximal 3 Tage(wenn nicht angegeben, wird die Standardgültigkeit von 86400 Sekunden, also einem Tag, verwendet).

Beispiel-Anfragetext

{
  "solution_id": "123456789111213",
  "api_key": "abc123", // Optional
  "ttl": 3600 // Optional
}

Beispiel Antwortkörper

Eine erfolgreiche Antwort gibt einen HTTP-Statuscode von 200 und enthalten einen Antwortkörper mit einem JSON-Objekt, das die generierte eingebettete Anmelde-URL sowie eine Trace-ID für die Anfrage enthält.

{
  "id": "3amb0119-0196-42d1-8fb5-55a98s133546",
  "url": "https://tools.vonage.com/wa/partners/onboard?token=fhdhhdJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MjU5Njc1OTYsImp0aSI6ImQ1MmJhNmFjLWYxZjktNDdmNC05MTR_cFT1bVfkDhP-wgpKZibSbUoh9z-9KGD-wsmHxi0h7tTidpVhPNShfC5jmgiHtOQKXXv5NWb9OqoUraOMMpqCdNdXoN3ao-PeZX7axyYW_FQ6CeV9gDEPhAZ4urTi0uW4mCYGl3ULmA9Ps92r_wi2DJyRE_Kx2KahWtQd51yVpU6FfXgMb4odREEccDctT1Peo09wKgwBa1wsOkD7rrvkoQPqZ00VXcqOY1_LOO5tq4WJaKqtxX-U7VtDo9qyVUl8pdegZW6QWChQzGN4PkqXXLWcBlyrCtAYdhtWG8q6NM_6bARRjcGJlj0tQvE0PZ9AtafAQSPpOll5lcnUK8Ds"
}

Überprüfen des Status der WhatsApp-Telefonverifizierungsnummer

Im Rahmen der Registrierung der WhatsApp Numbers wird ein One-Time Password (OTP) an die registrierte Nummer gesendet, um die Nummer zu verifizieren. Die Verifizierung muss erfolgreich abgeschlossen sein, bevor die Nummer verwendet werden kann.

Der Status der Nummernüberprüfung kann auf folgende Weise überprüft werden:

Hinweis: Kundenadministratoren erhalten auch eine E-Mail-Benachrichtigung und eine Meta Business Suite-Benachrichtigung über den Onboarding-Status.

Manuelle Überprüfung des Status einer Nummer

Um den Status einer Numbers manuell zu überprüfen, können Sie die WhatsApp Manager-Schnittstelle Ihrer WABA besuchen. Eine aktive Nummer zeigt einen Status von Verbunden.

Screenshot of WhatsApp Manager showing number status

Abonnieren von Updates zu einer Nummer

Sie können Aktualisierungen über die Änderung des Verifizierungsstatus einer Nummer abonnieren, indem Sie WhatsApp-Benachrichtigungsabonnements.

Abonnements können für viele verschiedene Ereignisse erstellt werden; mehr dazu erfahren Sie im Abschnitt WhatsApp-Benachrichtigungsabonnements Leitfaden Dokument. Für Statusaktualisierungen von Nummern müssen Sie ein Abonnement mit dem account_update Abonnementtyp in der whatsapp_subscribe_typesund auch die vonage_number_onboarded Abonnementtyp in der vonage_subscribe_types.

Die Benachrichtigung wird ausgelöst durch eine PARTNER_ADDED Ereignis und wird an den Webhook oder Slack-Hook gesendet, den Sie beim Erstellen des Abonnements angegeben haben. Die Nutzlast der Benachrichtigung enthält die waba_id, solution_idund owner_business_id Einzelheiten.

Die Nutzlast für eine POST Anfrage an den https://api.nexmo.com/v2/whatsapp-manager/subscriptions Endpunkt würde etwa wie folgt aussehen:

{
  "type": "webhook",
  "label": "#dk-test",
  "whatsapp_subscribe_types": "account_update", // or can be left blank ""
  "vonage_subscribe_types": "vonage_number_onboarded",
  "webhook": {
      "url" : "https://eo34s4y0tl.m.pipedream.net"
  }
}

Hinweis: Der Wert des id in der Antwort zurückgegeben, wenn Generieren einer eingebetteten Anmelde-URL korreliert mit dem Wert des onboarding_id Eigenschaft in der notification_value Objekt innerhalb der whatsapp Objekt in der Nutzlast der Benachrichtigung.

Verknüpfung einer WhatsApp-Nummer mit einer Vonage-Applikation

Damit die WhatsApp-Nummer zum Versenden von Nachrichten über die Vonage Messages API verwendet werden kann, muss sie mit einer Vonage Application verknüpft sein.

Dies kann entweder über die Funktion Vonage Dashboard oder über die Anwendung mit einem Account-Endpunkt verknüpfen der Externe Accounts API.

Hinweise für Partner

  • Für die Nutzung des Hosted Embedded Signup Flow durch einen Vonage Partner/Technologiedienstleister ist keine gesonderte Freischaltung erforderlich. Der Zugriff erfolgt über das Hauptmenü api-key und die zugehörigen Berechtigungsnachweise.
  • Nur "geteilte" WhatsApp Business Accounts (WABAs) von Kunden können neue WhatsApp Numbers über den Hosted Embedded Sign-up Flow oder einen Embedded Sign-up Flow einbinden. Für OBO WABAs muss das manuelle Onboarding verwendet werden. Bitte beachten Sie die Meta-Dokumentation für Einzelheiten über OBO und Shared WABAs.
  • Vonage Partner/Technologielieferanten sollten sicherstellen, dass ihre Kunden, die den Hosted Hosted Embedded Flow nutzen, die Business Details in ihrem Business Portfolio Info-Abschnitt ausgefüllt und ergänzt haben. Wenn erforderliche Details, z. B. die geschäftliche E-Mail-Adresse des Benutzers, ungültig sind, wird der Onboarding-Prozess wahrscheinlich fehlschlagen.
  • Bei der Registrierung von WhatsApp-Nummern kann die erwartete Antwortzeit der Meta-API bis zu 120 Sekunden betragen.
  • Die An- und Abmeldeversuche für jede WhatsApp Numbers sind durch Meta begrenzt (10 Versuche pro Number pro Woche). Nach Erreichen dieses Limits wird die Nummer für die Registrierung gesperrt.