WhatsApp

Ein Leezy-Agent lässt sich mit einer WhatsApp-Business-Rufnummer verbinden, sodass Kundinnen und Kunden direkt in WhatsApp mit der KI schreiben können.

Diese Anleitung führt durch die gesamte Einrichtung, einschließlich der Schritte bei Meta. Sie ist einmalig nötig und dauert beim ersten Mal etwa 30–45 Minuten. Ist eine Unternehmensverifizierung erforderlich, kommt zusätzliche Zeit hinzu.

Funktionsweise

Nach der Verbindung wird jede Nachricht an die WhatsApp-Nummer an Leezy weitergeleitet, der Agent erzeugt aus seinem trainierten Wissen eine Antwort, und diese geht über WhatsApp zurück. Die Gespräche erscheinen zusammen mit den Web-Chats im Reiter Activity.

Die Integration nutzt die offizielle WhatsApp Cloud API von Meta; Zustellung, Verschlüsselung und Erreichbarkeit liegen damit bei Meta.

Wem die Meta-App gehört

Die in der Einrichtung erzeugte Meta-App gehört dem einrichtenden Unternehmen, nicht Leezy. Leezy ist kein WhatsApp-Solution-Provider — jedes Unternehmen betreibt seine eigene Meta-App und verbindet eigene Zugangsdaten. Daraus folgt:

• Es ist kein Prüf- oder Freigabeverfahren bei Meta nötig. Die Meta-App darf im Entwicklerportal im Modus Development bleiben — das ist der normale Zustand für Cloud-API-Nachrichten und blockiert weder Senden noch Empfangen.
• Die Unternehmensverifizierung bei Meta ist zu Beginn optional. Sie hebt die Grenze von 250 Gesprächen pro Tag an und schaltet Marketing- und Template-Nachrichten frei, ist aber keine Voraussetzung für die Verbindung mit Leezy.
• Das temporäre Zugriffstoken direkt nach dem Anlegen der Meta-App verfällt nach 24 Stunden. Für den produktiven Einsatz tritt ein dauerhaftes System-User-Token (Phase 3) an seine Stelle.

Kurz: Die Registrierung bei Meta und die vier folgenden Phasen genügen. Keine Plattformprüfung, keine App-Einreichung, keine Wartezeit in einer Freigabeschlange.

Wer was bezahlt

Es gibt zwei getrennte Kostenströme, die vor dem Verbinden bekannt sein sollten:

Kosten	Empfänger	Hinweise
WhatsApp-Gesprächsgebühren (je Nachrichtensitzung)	Meta, abgerechnet gegenüber dem Unternehmen, dem das WhatsApp Business Account gehört	Die Preise hängen von Land und Gesprächskategorie ab (Service, Marketing, Utility, Authentifizierung). Die meisten Servicegespräche liegen zwischen 0,005 und 0,08 US-Dollar. Siehe Meta-Preisseite.
KI-Antworterzeugung	Leezy, abgezogen vom Kontingent des Workspace-Tarifs	Jeder WhatsApp-Austausch kostet 2 Nachrichteneinheiten (1 eingehend + 1 KI-Antwort), genau wie im Web-Widget.

Kurz: Das Unternehmen besitzt die Meta-App und zahlt Meta für die Zustellung; Leezy trägt die KI-Verarbeitung und zählt jeden Austausch auf das Tarifkontingent an.

Voraussetzungen

• Ein kostenpflichtiger Leezy-Workspace-Tarif. WhatsApp verbinden können Owner- und Admin-Rollen.
• Das Beta-Feature Integrations muss für den Workspace aktiv sein. Ohne dieses Merkmal erscheint WhatsApp nicht im Deploy-Bereich.
• Ein Facebook-Konto mit Zugriff auf ein Meta Business Account oder der Berechtigung, eines anzulegen.
• Eine Rufnummer, die nicht bei WhatsApp registriert ist (weder in der normalen App noch in WhatsApp Business). Sie muss SMS oder Anrufe zur Verifizierung empfangen können.
• Eine hinterlegte Kreditkarte im Meta Business Manager (Meta verlangt sie vor produktiven Nachrichten, auch bei geringem Volumen).

:::tip Testmodus ist kostenlos Meta stellt eine kostenlose Testrufnummer bereit, die ohne Unternehmensverifizierung an bis zu fünf vorab freigegebene Empfänger schreiben kann. Der gesamte Ablauf funktioniert mit dieser Nummer, sodass sich die Integration vollständig prüfen lässt, bevor Zahlungsdaten oder eine echte Rufnummer hinzukommen. :::

Überblick über die Einrichtung

Die Einrichtung verteilt sich auf vier Oberflächen:

1. Meta Business Manager — die Klammer auf Unternehmensebene.
2. Meta for Developers — hier liegt die Meta-App, die mit Leezy spricht.
3. Meta Business Settings → System Users — hier entsteht ein dauerhaftes Zugriffstoken.
4. Leezy — hier werden alle Werte eingetragen und die Webhook-URL zurück zu Meta kopiert.

Jede Phase endet mit einer Liste zu sichernder Werte. Nach Phase 3 sollten vier Werte notiert sein; Phase 4 verwendet sie.

---

Phase 1 — Meta Business Account

Das Meta Business Account ist die rechtliche Klammer um die WhatsApp-Verbindung. Das Anlegen ist kostenlos.

1.1 Business Account anlegen oder öffnen

1. business.facebook.com aufrufen und mit dem Facebook-Konto anmelden, dem die WhatsApp-Verbindung gehören soll.
2. Existiert noch kein Business Account, auf Konto erstellen klicken und Firmenname, verantwortliche Person und geschäftliche E-Mail-Adresse angeben.
3. Existiert bereits eines, dieses öffnen.

1.2 Business-Account-ID notieren

Diese ID wird gelegentlich für Supportanfragen gebraucht. Zu finden über das Zahnrad (⚙️) unten links → Unternehmenseinstellungen; die ID steht oben unter dem Firmennamen.

:::note Unternehmensverifizierung Meta begrenzt nicht verifizierte Unternehmen auf 250 einzelne Kundengespräche pro 24 Stunden. Für den Start ist die Verifizierung nicht nötig, vor einer Marketingkampagne aber einzuplanen. Sie dauert ein bis drei Werktage und verlangt ein Unternehmensdokument (Registerauszug, Rechnung eines Versorgers oder Steuerdokument). Start unter Unternehmenseinstellungen → Sicherheitscenter → Verifizierung starten. :::

---

Phase 2 — Meta-App mit WhatsApp anlegen

Die Meta-App hält die Zugangsdaten der WhatsApp Cloud API.

2.1 App anlegen

Meta führt in fünf Schritten durch die Erstellung: App-Details → Anwendungsfälle → Unternehmen → Anforderungen → Übersicht.

1. developers.facebook.com aufrufen und mit demselben Facebook-Konto anmelden.
2. Oben rechts auf My Apps und dann Create app klicken.
3. App-Details: Anzeigenamen (etwa „Acme Kundenservice") und Kontakt-E-Mail eintragen. Next.
4. Anwendungsfälle: Den WhatsApp-bezogenen Anwendungsfall wählen (oder „Other", falls angezeigt). Next.
5. Unternehmen: Das Business Account aus Phase 1 verknüpfen. Next.
6. Anforderungen / Übersicht: Angaben prüfen, Create app klicken und die Sicherheitsabfrage abschließen.

:::note Der Assistent ändert sich Meta gestaltet diesen Ablauf regelmäßig um; die Beschriftungen können abweichen. Entscheidend ist das Ergebnis: das App-Dashboard mit einer linken Navigation aus Dashboard, App Settings, App Roles, Notifications, App Review, Products, Webhooks. :::

:::tip „Development" ist der Normalzustand Nach dem Anlegen zeigt das Entwickler-Dashboard die App als In Development und blendet womöglich einen Hinweis zu App Review ein. Beides ist erwartbar und blockiert nichts. Cloud-API-Nachrichten sind für den Development-Modus ausgelegt — die App sendet und empfängt echte Nachrichten, ohne App Review und ohne Wechsel auf „Live". :::

2.2 WhatsApp-Produkt hinzufügen

1. Im Dashboard der neuen App zu Add products to your app scrollen.
2. Auf der WhatsApp-Karte Set up klicken.
3. Meta legt automatisch ein Test-WABA und eine Testrufnummer an. Das ist normal; die Testnummer lässt sich später ersetzen.
4. Es erscheint der Bildschirm API Setup. Diesen Tab geöffnet lassen — die meisten Werte für Phase 3 stammen von hier.

2.3 Phone Number ID und WABA-ID kopieren

Auf der Seite API Setup:

1. Das Auswahlfeld From listet alle registrierten Rufnummern. Direkt darunter steht die Phone number ID (15–17 Ziffern). Diesen Wert kopieren — das ist phone_number_id.
2. Darunter steht die WhatsApp Business Account ID. Diesen Wert kopieren — das ist waba_id.

:::caution Testnummer und Produktivnummer Die Phone Number ID der automatisch erzeugten Testnummer eignet sich für vollständige Tests, kann aber nur an fünf vorab freigegebene Empfänger schreiben (über das Feld To auf derselben Seite). Für den Produktivbetrieb auf Add phone number klicken und die Verifizierung mit einer Rufnummer durchlaufen, die nicht bei WhatsApp registriert ist. :::

2.4 App Secret kopieren

Das App Secret dient dazu, eingehende Webhook-Anfragen als echt zu erkennen.

1. In der linken Navigation App Settings → Basic öffnen (deutsche Oberfläche: App-Einstellungen → Allgemeines).
2. Beim Feld App Secret (deutsch: App-Geheimcode) auf Show / Anzeigen klicken, bei Aufforderung das Facebook-Passwort eingeben und den Wert kopieren. Das ist app_secret.

:::warning App Secret wie ein Passwort behandeln Es ist ein langlebiger Signaturschlüssel. Wer ihn besitzt, kann Webhook-Anfragen fälschen. Leezy speichert ihn verschlüsselt; er gehört dennoch nie in Chats, E-Mails oder Screenshots. :::

Prüfliste Phase 2

• phone_number_id
• waba_id
• app_secret

---

Phase 3 — Dauerhaftes Zugriffstoken erzeugen

Das Zugriffstoken berechtigt Leezy, im Namen der WhatsApp-Nummer zu senden. Da das temporäre Token nach 24 Stunden verfällt, ist ein System-User-Token erforderlich.

3.1 System-User anlegen

1. Meta Business Settings öffnen.
2. In der linken Navigation Users → System users wählen.
3. Auf Add klicken, einen Namen vergeben (etwa „Leezy Integration"), die Rolle Admin setzen und Create system user klicken.

3.2 WhatsApp Business Account zuweisen

1. Beim ausgewählten System-User auf Add assets klicken.
2. WhatsApp accounts wählen, das WABA aus Phase 2 markieren und Full control vergeben.
3. Auf Save changes klicken.

3.3 Zugriffstoken erzeugen

1. Auf der Seite des System-Users Generate new token (deutsch: Token generieren) klicken.
2. Der Dialog führt in vier Schritten:
   • App wählen: die Meta-App aus Phase 2.
   • Gültigkeit: Never (deutsch: Nie) wählen. Voreingestellt sind „60 Tage (empfohlen)" — siehe Hinweis unten.
   • Berechtigungen: Drei WhatsApp-Bereiche sind vorausgewählt:
     • whatsapp_business_messaging
     • whatsapp_business_management
     • whatsapp_business_manage_events Alle drei aktiviert lassen.
3. Auf Generate token klicken.
4. Das Token sofort kopieren. Das ist access_token. Es wird nicht erneut angezeigt; geht es verloren, muss ein neues erzeugt werden.

:::warning 60 Tage oder „Nie" Meta empfiehlt inzwischen eine Rotation alle 60 Tage und wählt diese Option vor. Never hält die Integration dauerhaft am Laufen, weicht aber von der Empfehlung ab. In sicherheitskritischen Umgebungen ist die 60-Tage-Variante samt Kalendererinnerung zur rechtzeitigen Erneuerung sinnvoll; für die meisten Teams ist Never ein vertretbarer Kompromiss. :::

:::warning Umgang mit dem Token Das Token erlaubt vollständiges Senden und Empfangen für die Rufnummer. Wie das App Secret speichert Leezy es verschlüsselt. Es gehört nicht in gemeinsam genutzte Dokumente. :::

Prüfliste Phase 3

• phone_number_id
• waba_id
• app_secret
• access_token

---

Phase 4 — In Leezy verbinden

4.1 Verbindungsbildschirm öffnen

1. In Leezy den Agenten öffnen, der WhatsApp-Nachrichten beantworten soll.
2. Deploy → WhatsApp aufrufen.
3. Auf Connect WhatsApp klicken.

4.2 Die vier Werte eintragen

Feld in Leezy	Wert aus Meta
Phone Number ID	phone_number_id (Phase 2.3)
WhatsApp Business Account ID	waba_id (Phase 2.3)
Access Token	access_token (Phase 3.3)
App Secret	app_secret (Phase 2.4)

Auf Connect klicken. Leezy prüft die Zugangsdaten bei Meta, speichert sie verschlüsselt und zeigt anschließend eine Webhook-URL und ein Verify Token. Beides kopieren — es wird im nächsten Schritt gebraucht.

4.3 Webhook bei Meta konfigurieren

Dieser Schritt legt fest, wohin Meta eingehende Nachrichten sendet. Alles geschieht auf einer Seite; ein separater Bearbeiten-Dialog existiert nicht.

1. Zurück zur Meta-App unter developers.facebook.com → WhatsApp → Configuration (deutsch: WhatsApp → Konfiguration).
2. Im Bereich Webhook oben auf der Seite:
   • Die Webhook-URL aus Leezy in Callback URL einfügen.
   • Das Verify Token aus Leezy in Verify token (deutsch: Verifizierungstoken) einfügen.
   • Auf Verify and save (deutsch: Bestätigen und speichern) klicken. Meta sendet eine einmalige Prüfanfrage und bestätigt bei Erfolg grün.
3. Unterhalb steht die Tabelle Webhook fields mit allen Ereignissen, über die Meta informieren kann. In der Zeile messages den Schalter auf Subscribed (deutsch: Abonniert) stellen. Die übrigen Felder bleiben deaktiviert.

:::tip Erst verifizieren, dann abonnieren Der Schalter bleibt nur aktiv, wenn die Callback-URL zuvor erfolgreich verifiziert wurde. Lässt er sich nicht setzen, URL und Verify Token aus Schritt 2 erneut prüfen. :::

4.4 Testnachricht senden

Von einem privaten WhatsApp-Konto an die Produktivnummer schreiben — oder, bei Nutzung der Testnummer, die eigene Nummer zunächst auf der Seite „API Setup" in die To-Liste aufnehmen und dann schreiben.

Innerhalb weniger Sekunden sollte eine KI-Antwort in WhatsApp eintreffen. Das Gespräch erscheint zusätzlich im Reiter Activity des Agenten.

Bleibt die Antwort aus, hilft der Abschnitt Fehlerbehebung.

---

Was heute möglich ist

Funktion	Status
Antworten auf eingehende Textnachrichten	✅ unterstützt
Nutzung des trainierten Wissens (RAG)	✅ unterstützt
Auslösen von KI-Werkzeugen (Leaderfassung, Ticketerstellung)	✅ unterstützt
Empfang von Bildern, Dokumenten, Sprachnachrichten	Wird mit Platzhaltertext quittiert; vollständige Medienverarbeitung ist geplant
Senden von Bildern, Dokumenten oder Schaltflächen	In v1 noch nicht unterstützt
Proaktive Nachrichten außerhalb des 24-Stunden-Fensters	Noch nicht unterstützt — erfordert von Meta freigegebene Vorlagen

Das 24-Stunden-Servicefenster

Meta erlaubt freie Nachrichten nur innerhalb von 24 Stunden nach der letzten Kundennachricht. Danach sind ausschließlich freigegebene Vorlagen möglich. Da Leezy v1 nur antwortet, spielt diese Regel praktisch keine Rolle: Jede Antwort folgt unmittelbar auf eine Kundennachricht und liegt damit im Fenster.

Fehlerbehebung

„Verify and save" schlägt fehl

• Prüfen, ob das Verify Token exakt und ohne führende oder folgende Leerzeichen eingefügt wurde.
• Prüfen, ob die Callback-URL vollständig kopiert wurde (sie endet auf /api/webhooks/whatsapp).
• Die Leezy-Verbindung muss noch aktiv sein — beim erneuten Öffnen des Verbindungsbildschirms erzeugt Reconnect ein frisches Verify Token.

Nachrichten gehen raus, aber es kommt keine Antwort

• Prüfen, ob das Webhook-Feld messages bei Meta abonniert ist (Phase 4.3). Das ist die häufigste Ursache.
• Im Reiter Activity prüfen: Erscheint die eingehende Nachricht dort, ohne dass eine Antwort folgt, ist womöglich das Tarifkontingent erschöpft.
• Bei Testrufnummern muss die absendende Nummer auf der Seite „API Setup" in der To-Liste stehen, sonst verwirft Meta die Nachricht vor Leezy.

Fehler „Invalid OAuth access token"

• Vermutlich wurde das temporäre Token von der Seite „API Setup" verwendet (Gültigkeit 24 Stunden). Stattdessen ein dauerhaftes System-User-Token nach Phase 3 erzeugen.
• Prüfen, ob beim Erzeugen sowohl whatsapp_business_messaging als auch whatsapp_business_management aktiviert waren.

Antworten kommen langsam oder in falscher Reihenfolge

• Meta begrenzt die Rate je Rufnummer. Ohne Verifizierung sind es 250 einzelne Gespräche pro 24 Stunden; darüber weist Meta Sendungen zurück.
• Die Unternehmensverifizierung (Phase 1.2) hebt diese Grenze an.

Verbindung trennen

In Leezy Deploy → WhatsApp → Disconnect wählen. Damit entfernt Leezy die Zugangsdaten und meldet den Webhook ab. Meta-App und Rufnummer bleiben bestehen und lassen sich jederzeit erneut verbinden.

Das vollständige Löschen des WhatsApp Business Account geschieht bei Meta unter Unternehmenseinstellungen → Konten → WhatsApp-Konten.

Häufige Fragen

Lässt sich dieselbe WhatsApp-Nummer parallel mit einem anderen Werkzeug nutzen? Nein. Eine WhatsApp-Business-Rufnummer kann jeweils nur mit einer Cloud-API-Integration verbunden sein. Zuerst die andere Verbindung trennen.

Können mehrere Agenten eine Rufnummer teilen? Nein. Jede Rufnummer gehört zu genau einem Agenten. Für mehrere Agenten sind mehrere Rufnummern bei Meta zu registrieren.

Speichert Leezy die Nachrichten? Ja — beide Richtungen liegen im Gesprächsverlauf des Agenten, wie bei Web-Chats. Sie sind im Reiter Activity sichtbar und zählen auf das Tarifkontingent an.

Wo liegen die Daten? Sämtliche Gesprächsdaten werden in der EU gespeichert.

Was passiert, wenn die Meta-App gelöscht oder das Token entzogen wird? Eingehende Nachrichten erreichen Leezy nicht mehr, ausgehende Antworten schlagen fehl. Die Verbindung meldet beim nächsten Versuch einen Fehler. Ein neues Token erzeugen und in Leezy Reconnect klicken.

Muss die Meta-App von Meta geprüft oder freigegeben werden? Nein. Die App bleibt im Modus Development, und das ist für Cloud-API-Nachrichten der richtige Zustand. Der App Review von Meta betrifft den Zugriff auf Konten anderer Unternehmen und ist hier nicht erforderlich.

Ist die Unternehmensverifizierung Pflicht? Für den Start nicht. Nicht verifizierte Business Accounts bewältigen bis zu 250 einzelne Gespräche pro 24 Stunden, was für Tests und kleine Installationen genügt. Die Verifizierung hebt diese Grenze an und ist für Marketing- und Vorlagennachrichten nötig.

Ist Leezy ein von Meta zugelassener WhatsApp-Solution-Provider? Nein, und die Integration setzt das nicht voraus. Jedes Unternehmen verbindet eine eigene Meta-App mit eigenen Zugangsdaten; die WhatsApp-Verbindung besteht damit unmittelbar zwischen Unternehmen und Meta. Leezy liefert die Agentenebene darüber.