Zum Hauptinhalt springen

📱 WhatsApp Cloud API

WhatsApp wird über Metas Cloud API verbunden — die offizielle, kostenlos verfügbare API, mit der Sie WhatsApp-Nachrichten von Ihrem eigenen Server senden und empfangen können. Kein Drittanbieter-BSP (Business Solution Provider) erforderlich.

Voraussetzungen​

  1. Ein Meta-Entwicklerkonto bei developers.facebook.com
  2. Ein Meta Business-Konto (auch Business Manager genannt)
  3. Eine Telefonnummer für WhatsApp, die nicht bereits bei persönlichem WhatsApp registriert ist (Sie können eine SIM, eine virtuelle Nummer oder einen Festnetzanschluss verwenden)

Einrichtungsschritte​

1. Meta-App erstellen​

  1. Gehen Sie zu developers.facebook.com/apps
  2. Klicken Sie auf Create App
  3. Wählen Sie den Typ Business
  4. Geben Sie einen Namen ein und verbinden Sie Ihr Business-Konto

2. WhatsApp-Produkt hinzufügen​

  1. Scrollen Sie im App-Dashboard zu Add Products to Your App
  2. Klicken Sie bei WhatsApp auf Set Up
  3. Wählen Sie Ihr Business-Konto

3. Zugangsdaten erhalten​

Navigieren Sie zu WhatsApp → API Setup in Ihrem App-Dashboard:

ZugangsdatenWo zu finden
Phone Number IDUnter der Sektion „From" aufgelistet — eine numerische ID wie 123456789012345
Access TokenDas temporäre Token auf dieser Seite. Für Produktion generieren Sie ein permanentes Token über System Users.
App SecretApp Dashboard → Settings → Basic → App Secret
Verify TokenEin String, den Sie selbst erstellen — ein beliebiger zufälliger String, z.B. my_secret_verify_token_2024

4. Kanal in PulseHub hinzufügen​

  1. Gehen Sie zu Kanäle → Kanal hinzufügen
  2. Wählen Sie WhatsApp
  3. Füllen Sie alle vier Felder aus
  4. Klicken Sie auf Kanal speichern
  5. Kopieren Sie die Webhook-URL von der Kanalkarte

5. Webhook in Meta konfigurieren​

  1. In Ihrer Meta-App gehen Sie zu WhatsApp → Configuration
  2. Klicken Sie auf Edit neben der Webhook-Sektion
  3. Callback URL: Fügen Sie Ihre PulseHub-Webhook-URL ein
  4. Verify Token: Geben Sie den gleichen String ein, den Sie in PulseHub verwendet haben
  5. Klicken Sie auf Verify and Save

Meta sendet eine GET-Anfrage an Ihre Webhook-URL mit ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... PulseHub prüft das Verify Token und gibt die Challenge zurück.

  1. Unter Webhook Fields abonnieren Sie: messages

6. Testen​

Senden Sie eine WhatsApp-Nachricht an Ihre Geschäftsnummer. Sie sollte als neue Konversation in PulseHubs Posteingang innerhalb von Sekunden erscheinen.

Signaturverifizierung​

Meta fügt jedem Webhook einen X-Hub-Signature-256-Header hinzu:

X-Hub-Signature-256: sha256=abc123...

PulseHub verifiziert ihn mit HMAC-SHA256 und Ihrem App Secret. Bei fehlgeschlagener Verifizierung gibt der Webhook 401 Signature mismatch zurück.

Nachrichten senden​

Wenn ein Agent eine Antwort aus dem Posteingang sendet, ruft PulseHub die WhatsApp Cloud API auf:

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Ihre Antwort hier"}
}

Produktionszugang​

Die Standard-Meta-App ist im Development-Modus — sie kann nur Nachrichten an als Testnummern hinzugefügte Nummern senden. Um live zu gehen:

  1. Schließen Sie die Business-Verifizierung im Meta Business Manager ab
  2. Reichen Sie Ihren WhatsApp-Anwendungsfall für Metas Review ein
  3. Nach Genehmigung erhält Ihre App Zugang, um Nachrichten an alle WhatsApp-Nutzer zu senden

Häufige Probleme​

SymptomWahrscheinliche Ursache
Verifizierung schlägt bei Webhook-Einrichtung fehlverify_token in PulseHub stimmt nicht mit dem in Meta eingegebenen überein
Signatur-Fehler in den LogsFalsches app_secret — kopieren Sie es aus App Settings → Basic, nicht aus API Setup
Nachrichten kommen nicht anWebhook-Feld messages nicht im Meta-Dashboard abonniert
Invalid phone number beim SendenNummernformat muss E.164 ohne + sein (z.B. 15551234567)
App im Development-Modus-FehlerNur verifizierte Testnummern können im Dev-Modus Nachrichten empfangen