WhatsApp mit FyneDesk verbinden

Bringen Sie eine WhatsApp-Business-Nummer in FyneDesk, sodass jede eingehende Nachricht zu einem Ticket wird und Ihr Team direkt aus dem Ticket heraus antwortet — keine separate WhatsApp-App nötig. Sie können direkt über die Cloud API von Meta oder über einen Anbieter wie Gupshup, 360Dialog oder Twilio verbinden.

Wie die Verbindung funktioniert FyneDesk liest das standardmäßige Nachrichtenformat der Meta Cloud API von WhatsApp. Meta direkt sowie Meta-Passthrough-Anbieter (Gupshup, 360Dialog, Twilio im Passthrough-Modus und andere) senden alle dasselbe Format — die Schritte innerhalb von FyneDesk sind also identisch, egal wer Ihre Nummer hostet. Das Einzige, was sich ändert, ist, von wo Sie Ihre Anmeldedaten kopieren. Finden Sie Ihren Anbieter in Schritt 2.

Was Sie benötigen

Eine WhatsApp-Business-Nummer, die bereits bei Ihrem Anbieter (oder direkt bei Meta) eingerichtet ist.
Administratorzugriff auf Ihre FyneDesk-Organisation.
Die Anmeldedaten Ihres Anbieters — in Schritt 2 sehen Sie genau, welche Werte zu kopieren sind.

Schritt 1 — Die Verbindung in FyneDesk hinzufügen

Gehen Sie in FyneDesk zu Administratoreinstellungen → WhatsApp und klicken Sie auf Verbindung hinzufügen. Wählen Sie unter Wo Ihr WhatsApp gehostet wird, wie Ihre Nummer gehostet wird: Meta Cloud API direkt, Gupshup, 360Dialog, Twilio (Meta-Passthrough-Modus) oder Anderer / benutzerdefinierter Anbieter.

Füllen Sie dann das Formular aus:

WhatsApp-Business-Telefonnummer — die Nummer, an die Kunden schreiben, im internationalen Format (z. B. +55 11 99999-9999).
Phone Number ID — die lange numerische ID aus dem Dashboard Ihres Anbieters, nicht die sichtbare Telefonnummer.
Access Token — das Token oder der API-Schlüssel Ihres Anbieters (Schritt 2). Verschlüsselt gespeichert; nach dem Speichern wird es nie wieder angezeigt.
WhatsApp Business Account ID — optional.
App Secret — der Wert, den Ihr Anbieter als App Secret oder Webhook Signing Secret bezeichnet. FyneDesk verwendet ihn, um zu überprüfen, dass jede eingehende Nachricht wirklich von WhatsApp stammt.
Akzeptierte Nachrichtentypen — Text, Bilder und Dokumente.

Klicken Sie auf Speichern und verbinden.

FyneDesk-Formular zum Hinzufügen einer WhatsApp-Verbindung mit einem Anbieter-Dropdown „Wo Ihr WhatsApp gehostet wird“ und Feldern für die WhatsApp-Business-Telefonnummer, Phone Number ID, Access Token, WhatsApp Business Account ID und App Secret sowie Nachrichtentyp-Kontrollkästchen für Text, Bilder und Dokumente

Schritt 2 — Ihre Anmeldedaten von Ihrem Anbieter holen

Suchen Sie den Abschnitt, der dem in Schritt 1 gewählten Anbieter entspricht, kopieren Sie die Werte und fügen Sie sie in das Formular ein.

Meta Cloud API direkt

Öffnen Sie developers.facebook.com, gehen Sie zu Ihrer App und dann zu WhatsApp → API Setup:

Phone Number ID und WhatsApp Business Account ID (WABA-ID) werden auf dieser Seite angezeigt.
Klicken Sie auf Generate token für das Access Token.
App Secret finden Sie unter App Settings → Basic → App Secret → Show.

Verwenden Sie für die Produktion ein dauerhaftes Token Das Token aus API Setup ist temporär und läuft nach 24 Stunden ab. Erstellen Sie für eine Live-Verbindung einen Systembenutzer in den Meta-Business-Einstellungen und generieren Sie ein nicht ablaufendes Token. Siehe Metas Leitfaden zu WhatsApp-Access-Tokens. Das Token benötigt die Berechtigungen whatsapp_business_messaging und whatsapp_business_management.

Gupshup

Öffnen Sie hub.gupshup.io, öffnen Sie Ihre WhatsApp-App und gehen Sie zu Settings:

Kopieren Sie Ihren API key und fügen Sie ihn in das Feld Access Token von FyneDesk ein.
Kopieren Sie Ihre Telefonnummer, Ihren App-Namen und die Phone Number ID.
Verwenden Sie für App Secret den Wert, den Gupshup als Webhook Signature Secret bezeichnet (unter Settings → Webhook).

Gupshup leitet Metas Webhook-Format unverändert weiter, sodass FyneDesk dieselbe Nutzlast liest, egal ob Sie Meta direkt oder Gupshup verwenden.

360Dialog

Öffnen Sie im 360Dialog-Hub den Kanal für Ihre Nummer:

Generieren Sie Ihren API key (360Dialog nennt ihn D360-API-KEY) und fügen Sie ihn in das Feld Access Token von FyneDesk ein. Jede Nummer hat ihren eigenen Schlüssel, und nur der neueste Schlüssel bleibt gültig.
Kopieren Sie Ihre Phone Number ID und die WABA-ID aus dem Hub.
Die Auswahl von 360Dialog in Schritt 1 weist FyneDesk an, für Sie über den Endpunkt von 360Dialog (waba-v2.360dialog.io) zu leiten.

Hinweis zum Neugenerieren von Schlüsseln Wenn Sie einen neuen 360Dialog-API-Schlüssel generieren, funktioniert der alte nicht mehr und der Webhook für diese Nummer wird gelöscht. Wenn das passiert, fügen Sie den neuen Schlüssel in FyneDesk ein und führen Sie Schritt 3 erneut aus, um den Webhook erneut festzulegen.

Twilio (Meta-Passthrough-Modus)

FyneDesk benötigt das native Meta-Webhook-Format von WhatsApp. Die standardmäßigen WhatsApp-Webhooks von Twilio verwenden Twilios eigenes Format, das FyneDesk nicht lesen kann — daher muss Ihre Twilio-Nummer im Meta-Passthrough-Modus eingerichtet sein, in dem Twilio Metas Roh-Webhooks unverändert weiterleitet.

Aktivieren Sie Meta-Passthrough für Ihren WhatsApp-Sender in Twilio und verwenden Sie dann Ihre Meta-Cloud-API-Anmeldedaten (Phone Number ID, Access Token, App Secret) für diese Nummer, genau wie im Meta-Abschnitt oben.
Siehe Twilios WhatsApp-Business-Platform-Dokumentation zum Aktivieren von Passthrough in Ihrem Konto.

Wenn Ihre Twilio-Nummer nicht im Meta-Passthrough-Modus laufen kann, verbinden Sie sie stattdessen über Meta Cloud API direkt oder einen anderen unterstützten Anbieter.

Anderer / benutzerdefinierter Anbieter

Jeder Anbieter, der das Cloud-API-Webhook-Format von Meta weiterleitet, funktioniert. Fügen Sie die Anmeldedaten, die Ihnen Ihr Anbieter gibt, in die passenden Felder ein. Wenn Ihr Anbieter einen anderen API-Endpunkt oder Authentifizierungs-Header verwendet, öffnen Sie Erweiterte Einstellungen anzeigen im Formular, um die ausgehende Basis-URL und den Auth-Header festzulegen. Verwenden Sie für das Feld App Secret das, was Ihr Anbieter als App Secret oder Webhook Signing Secret bezeichnet.

Schritt 3 — Die Einrichtung bei Ihrem Anbieter abschließen

Nach dem Speichern zeigt FyneDesk ein Banner mit einer Webhook-URL und einem Verify Token. Kopieren Sie beide in die Webhook-Einstellungen Ihres Anbieters und abonnieren Sie eingehende Nachrichten.

FyneDesk gibt Ihnen die Webhook-URL Die Webhook-URL ist einzigartig für Ihre Verbindung — FyneDesk generiert sie und zeigt sie zum Kopieren an. Sie erstellen sie nicht selbst. Fügen Sie den Verify Token genau ein, ohne zusätzliche Leerzeichen.

Wo sich die Webhook-Einstellung befindet, nach Anbieter:

Meta Cloud API direkt — WhatsApp → Configuration → Webhook: Fügen Sie die Webhook-URL als Callback URL und den Verify Token ein, klicken Sie auf Verify and save und abonnieren Sie dann das Feld messages.
Gupshup — Settings → Webhook: Fügen Sie die Webhook-URL und den Verify Token ein und aktivieren Sie das Ereignis messages (optional message_event für den Zustellstatus).
360Dialog — legen Sie die Webhook-URL für Ihre Nummer im 360Dialog-Hub fest. (Denken Sie daran, dass sie gelöscht wird, wenn Sie den API-Schlüssel neu generieren.)
Twilio — richten Sie den eingehenden Webhook Ihres WhatsApp-Senders auf die FyneDesk-Webhook-URL.
Anderer / benutzerdefiniert — fügen Sie die Webhook-URL in das Callback-/Webhook-Feld Ihres Anbieters ein und aktivieren Sie Ereignisse für eingehende Nachrichten.

Schritt 4 — Die Verbindung testen

Klicken Sie zurück in FyneDesk in der Verbindungszeile auf Verbindung testen. Ein grünes Häkchen bedeutet, dass Anmeldedaten und Webhook funktionieren. Senden Sie dann eine echte Testnachricht: Schreiben Sie von einem privaten WhatsApp an Ihre Business-Nummer. Sie sollte innerhalb von etwa fünf Sekunden als neues Ticket in FyneDesk erscheinen.

Ein FyneDesk-Ticket, das aus einer eingehenden WhatsApp-Nachricht erstellt wurde — die Nachricht des Kunden erscheint in der Unterhaltung, mit einem Feld „Per WhatsApp antworten“ darüber und einer darunter eingefügten Antwort eines Mitarbeiters

Das war's Eingehende WhatsApp-Nachrichten öffnen sich nun als Tickets, und Mitarbeiter antworten über das Feld Per WhatsApp antworten auf dem Ticket. Antworten werden dem Kunden auf WhatsApp zugestellt.

Fehlerbehebung

Die WhatsApp-Verbindung funktioniert nicht — häufige Lösungen

„Webhook-Verifizierung fehlgeschlagen.“ Der Verify Token bei Ihrem Anbieter muss genau mit dem übereinstimmen, den FyneDesk Ihnen gegeben hat. Kopieren Sie ihn erneut und prüfen Sie auf ein versehentliches Leerzeichen am Anfang oder Ende.

„Signatur ungültig“ in Ihrem FyneDesk-Audit-Log. Das App Secret / Webhook Signing Secret wurde falsch eingefügt. Kopieren Sie es erneut von Ihrem Anbieter und fügen Sie es erneut in die Verbindung ein.

„Token abgelaufen“ (Meta direkt). Sie haben ein temporäres 24-Stunden-Token verwendet. Erstellen Sie einen Systembenutzer in Meta und generieren Sie ein nicht ablaufendes Token, und aktualisieren Sie es dann in der Verbindung.

„Verbindung testen“ schlägt mit einem 401 fehl (Meta direkt). Dem Token fehlen Berechtigungen — es benötigt sowohl whatsapp_business_messaging als auch whatsapp_business_management.

360Dialog hat nach dem Erstellen eines neuen Schlüssels aufgehört zu funktionieren. Das Neugenerieren des API-Schlüssels löscht den Webhook und macht den alten Schlüssel ungültig. Fügen Sie den neuesten Schlüssel in FyneDesk ein und führen Sie Schritt 3 erneut aus.

Der Gupshup-Test schlägt fehl. Gupshup führt separate Sandbox- und Produktions-API-Schlüssel — stellen Sie sicher, dass Sie den Produktionsschlüssel verwenden.

Twilio-Nachrichten kommen nicht an. Das Standard-Webhook-Format von Twilio wird nicht unterstützt. Bestätigen Sie, dass die Nummer im Meta-Passthrough-Modus ist, sodass sie Metas native Webhooks weiterleitet.

Eingehende Nachrichten zeigen den falschen Absendernamen. WhatsApp liefert den eigenen Profilnamen des Kontakts, sodass Sie das sehen, was der Kunde in seinem Konto eingestellt hat. Das ist zu erwarten.