Erste Schritte
In diesem Tutorial erfährst du, wie du deinen On-Premises API-Client einrichten, deine geschäftliche Telefonnummer registrieren, deine Einstellungen aktualisieren und eine Testnachricht senden kannst.
Die ersten Schritte mit dieser API können in drei Hauptteile unterteilt werden:
- Assets vorbereiten — Bevor du loslegen kannst, musst du die für das Abschließen deiner API-Integration erforderlichen Assets einrichten. Dazu gehört auch ein WhatsApp Business Account.
- Den On-Premises API-Client installieren — Installiere den API-Client. Sobald dein Client funktioniert, kannst du deine App-Einstellungen ändern.
- Mit der Verwendung des Client beginnen – Registriere deine Telefonnummer durch einen API-Aufruf an
/accountund sende eine Testnachricht durch einen Aufruf von/messages.
Bevor du beginnst
Du benötigst Folgendes:
- Ein Facebook Business Manager-Konto
- Eine Kreditlinie für dein WhatsApp Business-Konto: Unter Abrechnungen für die On-Premises API findest du auch weitere Informationen zum Abrechnungsprozess.
- Ein Befehlszeilentool wie Terminal oder eine App wie Postman, die cURL-Anfragen stellen kann.
Nachdem du dein Unternehmen verifiziert hast, wird es auf Konformität mit den WhatsApp-Nutzungsbedingungen und der WhatsApp-Handelsrichtlinie überprüft. Dieser Schritt wird automatisch eingeleitet. Du kannst den Status der Unternehmensverifizierung und -überprüfung auf dem Tab Einstellungen deines WhatsApp Business-Kontos in Business Manager überprüfen. Als Status der Unternehmensverifizierung wird Verifiziert und als Account-Status nach erfolgter Genehmigung Genehmigt angezeigt.
Dein WhatsApp-Konto einrichten
Füge eine Telefonnummer mit zugehörigem Display-Namen zu deinem WhatsApp Business-Konto hinzu. Der Display-Name wird zur Überprüfung gesendet.
Wenn du den Display-Namen ändern möchtest, kannst du dies beliebig oft tun, bis du die Registrierung abschließt. Danach musst du zwischen Anfragen zum Ändern des Display-Namens 30 Tage warten.
Wenn alle Überprüfungen abgeschlossen sind, kannst du dein Base64-codiertes Zertifikat, das du für die Registrierung deines On-Premises API-Clients benötigst, anzeigen und aufrufen. Wir empfehlen, zum Starten der Integration bei der Registrierung zunächst einen genehmigten Display-Namen anzugeben, bevor du weitere Änderungen an einem Display-Namen vornimmst. Nach der Integration kannst du deinen Display-Namen jederzeit ändern.
Abrechnungs- und Preisinformationen überprüfen
Wenn dein Unternehmen Nachrichten über die On-Premises API versendet, ist es wichtig, den Abrechnungsprozess zu kennen. Du solltest etwa wissen, wie und wann du Rechnungen erhältst, wo sie zu finden sind und wie du sie bezahlst. Weitere Informationen findest du unter Abrechnung für dein WhatsApp Business-Konto. Auf unserer Seite Preisgestaltung erfährst du mehr über die Preisgestaltungsregeln und die Kosten pro Nachricht.
Empfohlene Softwareversionen
| Software | Version | Details |
|---|---|---|
On-Premises API | ||
On-Premises API für AWS | Überprüfe das Änderungsprotokoll Vorlagenversion: | |
MySQL |
| Beachte, dass die Datenbankmigration zu MySQL 8 nicht auf MySQL 5 herabgestuft werden kann. Erstelle daher vor der Migration ein Backup der Datenbank. |
PostgreSQL |
|
|
Docker | Mindestens Version | Version Stelle sicher, dass statx syscall in der Positivliste für syscalls für den Docker enthalten ist. |
Postman | Beliebige aktuelle Version | |
libseccomp |
| Nur |
glibc |
| Wird nur ab Version |
Betriebssystem (Operating System, OS) | Die aktuellste Version | Es muss mindestens Kernelversion |
Schritt 1: Den On-Premises API-Client installieren
Umgebung
Grundsätzlich basiert der On-Premises API-Client auf Docker. Informationen zu jeder Komponente findest du unter Client-Architektur.
Derzeit unterstützt der On-Premises API-Client Docker für Windows oder Untersysteme von Windows für Linux nicht. Für Entwicklungsanforderungen wird die Ausführung von Docker auf einem virtuellen Linux-Gerät empfohlen. Für Produktions-Workloads empfehlen wir einen Linux-Server, um Kompatibilitäts- und Leistungsprobleme zu vermeiden.
Geräte
Der On-Premises API-Client kann auf jedem mit dem Internet verbundenen Gerät ausgeführt werden, auf dem Docker für Linux ausgeführt werden kann, entweder in einer virtuellen Maschine oder auf Linux-Server. Weitere Informationen findest du in den FAQs. Auf einem Laptop können beispielsweise ganz einfache Tests durchgeführt werden. Für einen Produktionsumgebungsserver empfehlen wir mindestens 250 GB SSD, 16 GB RAM und Quad-Core-CPU. HDD wird nicht empfohlen, da die I/O-Geschwindigkeiten bei Auslastung zu Engpässen führen.
In den meisten Fällen solltest du die Datenbank auf einem physischen Server ausführen, der von Coreapp und Webapp-Containern getrennt ist. Die Latenzzeit zwischen dem Datenbankserver und anderen Rechnern sollte nur wenige Millisekunden betragen.
Installation
Es gibt zwei Arten, auf die du mit der On-Premises API loslegen kannst:
- On-Premise-Installation: Du kannst die Docker-Container selbst mithilfe des Installationsleitfadens einrichten. Wir empfehlen dir, mit einem der Developer-Setups zu beginnen. So kannst du dich mit dem Setup-Prozess und dem Senden von Nachrichten vertraut machen. Diese Vor Ort-Lösung kannst du auf deinem Computer verwenden, bevor eine Migration zu einer Produktionsumgebung stattfindet.
- Amazon Web Services (AWS): Wenn du AWS verwendest oder gerne eine eigenständige Lösung hättest, findest du im AWS-Leitfaden weitere Informationen dazu. Die AWS-Lösung richtet eine vollständige On-Premises API-Lösung mit Sicherungen, Wiederherstellung und vielem mehr in einer AWS-Cloud ein, die du selbst verwaltest und besitzt.
Sobald der On-Premises API-Client ausgeführt wird, musst du als adminangemeldet sein, um die übrigen Einrichtungsschritte ausführen zu können.
Deine Einstellungen aktualisieren
Sobald der On-Premises API-Client ausgeführt wird, kannst du Änderungen an den Anwendungseinstellungen vornehmen. Du kannst jedoch erst dann auf die anderen Profileinstellungen des On Premises API-Clients zugreifen, wenn die Registrierung abgeschlossen ist.
- Die Anwendungseinstellungen steuern, wie der Client funktioniert – Rückrufeinstellungen, Webhooks, On-Call-Pager, Gesendet-Status, Verhalten beim Medien-Download usw. Hinweis: Du solltest unbedingt eine Webhook-URL einrichten, um Benachrichtigungen über eingehende Nachrichten oder Fehler zu erhalten.
- Die Unternehmensprofil-Einstellungen und Profileinstellungen enthalten Informationen zu deinem Unternehmen, z. B. Adresse, E-Mail-Adresse, Website, Branche, Informationen über das Unternehmen und Profilfoto.
Schritt 2: Mit der Verwendung des Client beginnen
Registrierung
Sobald der On Premises API-Client eingerichtet ist und ausgeführt wird, kannst du deine Telefonnummer registrieren. Hierzu sendest du einen API-Aufruf an den Endpunkt account.
Eine Testnachricht senden
Du kannst Testnachrichten mit dem Endpunkt messages senden. Überprüfe zunächst den Status der Telefonnummer für den Test. Du musst einem WhatsApp Account eine Nachricht von der Test-Telefonnummer senden, um das Kundenservice-Fenster zu aktivieren. Dann kannst du innerhalb von 24 Stunden jede Art von Nachricht senden (weitere Informationen findest du unter Cut-off-Steuerung). Sende dann eine Textnachricht an deine Test-Telefonnummer. Kommt die Nachricht an, war die Installation erfolgreich. Kommt sie nicht an, überprüfe deinen Webhook auf Benachrichtigungen, die ggf. auf Probleme hinweisen.
Sicherheit
Informationen zu Passwörtern, Authentifizierung, SSL-Konfiguration, Netzwerktrennung, verschlüsselter Kommunikation, HTTP-Headern und zum TLS-Protokoll des Webservers in Zusammenhang mit dem On-Premises API-Client findest du in unserem Leitfaden zur Sicherheit.
Startvorgang
Die WhatsApp On-Premises API führt beim Herstellen einer Verbindung mit dem Server einen Startvorgang aus. Dieser Vorgang ist wichtig, um Nachrichten reibungslos und zuverlässig zu senden und zu empfangen. Während dieser Startphase wartet die Kernanwendung (coreapp) darauf, dass unter anderem die folgenden Voraussetzungen erfüllt werden:
Laden von Vorlagennachrichten: Die API lädt während des Initialisierungsvorgangs die Vorlagennachrichten vom Server.
Empfangen und Verarbeiten von Offline-Nachrichten: Die API übernimmt außerdem den Empfang und die Verarbeitung von Offline-Nachrichten.
Wenn versucht wird, Nachrichten zu senden, während diese Voraussetzungen nicht erfüllt sind, antwortet die Kernanwendung mit der Fehlermeldung „Coreapp not ready“ und in den Protokollen wird der Fehler „Service not ready“ angezeigt. Beachte, dass dieser Startvorgang jedes Mal ausgeführt wird, wenn eine neue Verbindung mit dem WhatsApp-Server hergestellt wird. Wenn die Kernanwendung also neu gestartet oder die Verbindung unterbrochen wird, wird der Startvorgang erneut eingeleitet, um den Status der Kernanwendung auf „bereit“ zu setzen. Dies gewährleistet die Zuverlässigkeit und Bereitschaft der WhatsApp On-Premises API für die Nachrichtenkommunikation.
Verarbeitung von Offline-Nachrichten
Wenn keine Offline-Nachrichten gefunden werden können, entfällt der Schritt der Offline-Nachrichtenverarbeitung. Mit anderen Worten: Wenn keine Nachrichten im Offline-Zustand warten, wird diese Phase der Nachrichtenverarbeitung übersprungen.
Unter gewöhnlichen Bedingungen folgt die WhatsApp On-Premises API einem Standardprotokoll für die Verarbeitung von Offline-Nachrichten. Sie wartet auf den Empfang und die Verarbeitung aller Offline-Nachrichten mit einer vordefinierten maximalen Zeitüberschreitung von 6 Minuten. Nach Ablauf dieser 6 Minuten gilt die Phase der Offline-Nachrichtenverarbeitung als erfolgreich abgeschlossen.
Zusätzliche Vorschläge
RICHTIGTeste das Versenden und Empfangen von Nachrichten zunächst mit internen Mitarbeitern. So kannst du dich von der Funktionsfähigkeit des Systems überzeugen. Antworte allen Kund*innen innerhalb von 24 Stunden. Halte dich an unsere in der WhatsApp Business-Richtlinie und WhatsApp-Handelsrichtlinie beschriebenen Richtlinien. Verwende mehrere Telefonnummern für Entwicklung, Tests und Produktion. Wirf einen Blick in die FAQs, bevor du ein Direct Support-Ticket öffnest. Gib Feedback zum Produkt. Direct Support eignet sich dazu am besten. Gib Details an, damit dein Problem reproduziert werden kann, z. B. Protokolle, Supportinformationen aus den Nodes | FALSCHSende Benachrichtigungen doppelt über mehrere Kanäle. Sende Spam. Verwende 0800-Nummern für Tests. Erstelle einen Business Manager nur für WhatsApp-Integrationen. Verwende einen vorhandenen, wenn verfügbar. |
Wir behalten uns das Recht vor, deinen Zugriff auf WhatsApp einzuschränken oder zu sperren, wenn wir feststellen, dass du eine unserer Richtlinien oder Strategien verletzt hast.