Verbinden Sie eine WhatsApp-Business-Nummer über Meta-Cloud-API-Zugangsdaten und signierte Webhooks.
Verbinden Sie eine WhatsApp-Business-Nummer über Meta-Cloud-API-Zugangsdaten und signierte Webhooks.
Meta-App und Nummer vorbereiten#
Folgen Sie der offiziellen Einstiegsanleitung zur WhatsApp Cloud API von Meta, um eine Meta-App zu erstellen oder auszuwählen, das WhatsApp-Produkt hinzuzufügen und ein WhatsApp-Business-Konto sowie eine Telefonnummer zuzuordnen.
Besorgen Sie sich diese drei Werte aus derselben App und für dieselbe Nummer:
| Feld in Make Agent Fast | Wert des Anbieters | Hinweise |
|---|---|---|
| Phone number ID | Numerische Phone Number ID | Dies ist weder die sichtbare Telefonnummer mit + noch die WABA-ID |
| Access token | Cloud-API-Zugriffstoken | Temporäre Dashboard-Tokens laufen ab; verwenden Sie für den Produktivbetrieb ein geeignetes langlebiges System-User-Token |
| App secret | Meta-App-Secret | Ein hexadezimales Secret mit 32 Zeichen, das zur Überprüfung der Webhook-Signatur dient |
Erteilen Sie nur die Berechtigungen, die für die Nummer und den Messaging-Workflow erforderlich sind. Halten Sie Entwicklungs- und Test-Assets getrennt von der Produktivnummer.
Zugangsdaten speichern und validieren#
Öffnen Sie die Seite Kanäle des Agents, wählen Sie WhatsApp, geben Sie alle drei Werte ein, aktivieren Sie bei Bedarf Mit Sprachnachricht antworten und klicken Sie auf Verbinden.
Make Agent Fast validiert die Nummer über die Graph API mithilfe des Zugriffstokens und appsecret_proof. So werden eine falsche Nummer, ein falsches Token oder ein falsches App-Secret erkannt, bevor Webhook-Traffic eintrifft. Anschließend zeigt die Connector-Karte eine eindeutige Webhook-URL und ein Verifizierungstoken an.
Meta-Webhook konfigurieren#
Gehen Sie in derselben Meta-App wie folgt vor:
- Öffnen Sie die WhatsApp-Webhook-Konfiguration.
- Fügen Sie die Webhook-URL des Connectors als Callback-URL ein.
- Fügen Sie das Verifizierungstoken des Connectors exakt ein; die Groß- und Kleinschreibung ist relevant.
- Schließen Sie die Verifizierung ab.
- Abonnieren Sie das WhatsApp-Business-Konto bzw. die Nummer für das Webhook-Feld
messages. - Stellen Sie sicher, dass die App und die Business-Assets für die vorgesehenen Test- oder Produktivnutzer verfügbar sind.
Das Verifizierungstoken belegt den Besitz während der GET-Verifizierungsanfrage. Laufzeit-POST-Anfragen werden separat über die Signatur mit dem Meta-App-Secret authentifiziert; ersetzen Sie das eine nicht durch das andere.
Text und Sprache testen#
Senden Sie zunächst eine Nachricht von einer zugelassenen Testnummer. Im Entwicklungsmodus von Meta können nicht registrierte Nutzer die App unter Umständen nicht erreichen. Prüfen Sie den Thread und den Kanal unter Unterhaltungen und beobachten Sie Letzte Nachricht auf der Connector-Karte.
Eingehende Text- und Sprachnachrichten werden unterstützt. Wenn Mit Sprachnachricht antworten aktiviert und die Sprachausgabe konfiguriert ist, lädt Make Agent Fast das generierte Audio über die Cloud API hoch und sendet es zusammen mit der Textantwort. Bilder, Standorte, Kontakte und andere nicht unterstützte Nachrichtentypen werden ignoriert.
Produktionsreife#
Bevor Sie die Nummer bewerben, schließen Sie die für Ihren Anwendungsfall erforderlichen Schritte von Meta ab: Business-Verifizierung, App-Review, Anzeigename, Vorlagen und Messaging-Richtlinien. Diese Anforderungen werden von Meta festgelegt und können sich unabhängig von Make Agent Fast ändern.
Verwenden Sie Produktivzugangsdaten mit einem klar benannten Verantwortlichen und einem Verfahren für Ablauf und Rotation. Dokumentieren Sie, welche Meta-App, welcher System-User, welche WABA und welche Phone Number ID zu diesem Connector gehören, damit ein Administrator ihn rotieren kann, ohne raten zu müssen.
Rotieren oder trennen#
Erstellen Sie ein Ersatztoken mit demselben Asset-Zugriff, aktualisieren Sie den Connector, senden Sie eine Testnachricht und widerrufen Sie erst dann das alte Token. Wenn sich das App-Secret ändert, aktualisieren Sie es sofort in Make Agent Fast, da sonst jeder signierte eingehende Webhook fehlschlägt.
Das Deaktivieren oder Entfernen des Connectors kündigt das Webhook-Abonnement bei Meta nicht und löscht die Webhook-Konfiguration dort nicht. Entfernen Sie auch das Abonnement beim Anbieter, wenn Sie die Nummer endgültig außer Betrieb nehmen.
Fehlerbehebung#
| Symptom | Lösung |
|---|---|
| Zugangsdaten werden abgelehnt | Prüfen Sie, ob das Token die exakte Phone Number ID lesen kann und das App-Secret aus derselben App stammt |
| Meta kann den Callback nicht verifizieren | Verwenden Sie die kopierte HTTPS-URL und das exakte Verifizierungstoken; stellen Sie sicher, dass der Connector noch vorhanden ist |
| Verifizierung erfolgreich, aber es treffen keine Nachrichten ein | Abonnieren Sie messages und prüfen Sie die Zuordnung von WABA und Nummer, den App-Modus, den Zugriff der Testnutzer sowie die Zustellprotokolle des Anbieters |
| Webhooks liefern „unauthorized“ | Geben Sie das korrekte App-Secret erneut ein; Meta-POST-Signaturen verwenden nicht das Verifizierungstoken |
| Ausgehende Antworten schlagen fehl | Prüfen Sie Token-Ablauf, Nummernberechtigungen, Empfängerrichtlinien bzw. Zeitfenster und Graph-API-Fehler |
| Text funktioniert, Audio nicht | Prüfen Sie die API-Schlüssel für Transkription bzw. Sprachausgabe sowie den Zugriff des Tokens auf Medien-Upload und -Download |
Geben Sie das Zugriffstoken und das App-Secret niemals in Browser-Code preis. Verwenden Sie die Public API nur von einem vertrauenswürdigen Server aus, wenn Sie die Erstellung von Connectors automatisieren.