> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp (Text + Voice) > WhatsApp Business Cloud API für Chat und Plattform-Sprachanrufe verbinden WhatsApp ist ein Workspace-Kanal unter **Settings → Channels → WhatsApp** – für Text-Chat, plattformseitige Sprachanrufe und Nachrichtenvorlagen. | Modus | Verfügbarkeit | | ------------ | ----------------------------------------------------------- | | Text-Chat | Enthalten mit WhatsApp-Messaging-Zugang | | Voice-Anrufe | Enthalten mit WhatsApp-Voice-Zugang | | Templates | Nutzt denselben WhatsApp-Business-Account wie der Text-Chat | **Bevorzugtes Onboarding (nur Plattform-Domain, z. B. app.famulor.io):** [WhatsApp Embedded Signup](/de/channels/whatsapp-embedded-signup) (Connect with Meta). Auf Whitelabel-Custom-Domains nutzen Workspaces ausschließlich das **manuelle Einfügen von Zugangsdaten**. **Marketplace-Nummern** (Settings → Numbers) sind **PSTN/SIP** für Telefon-Voice. Dieselbe E.164-Nummer wird erst dann WhatsApp-fähig, wenn Meta sie verifiziert hat (OTP). Deine SIP-Trunk-Einstellungen sind unabhängig von der WhatsApp Cloud API. Die SMS-Helfer der Plattform sind ausschließlich für SMS/MMS – nicht für WhatsApp. ## Voraussetzungen Dein Plan enthält WhatsApp Text und/oder WhatsApp Voice. ## Produkt-UI 1. **Connect with Meta** (Embedded Signup) – Assistent auswählen, optionale Marketplace-Nummer, OTP-Helfer für Marketplace-SMS 2. Oder Zugangsdaten manuell einfügen (Token, App Secret, Verify Token, Phone Number ID, WABA-ID) 3. Toggles: Text / Voice Inbound / Voice Outbound 4. **Edit** bei einer Verbindung → WhatsApp Sender Details: die Chat- und Outbound-Voice-Assistenten, **AI Auto-Responses**, **Keep conversations unread**, Anruf-Bereitschaft (**Enable calling on Meta**) sowie das Business-Profil (**About**, Description, Business Address, Business Category, Logo, Banner, Websites und Kontakt-E-Mails/-Telefonnummern). **Sync** überträgt das Profil zu Meta – das Logo wird dein WhatsApp-Profilbild. 5. Wähle **Templates** neben einem Sender, um dessen eigene Template-Seite zu öffnen. **Sync with Meta** folgt jeder Ergebnisseite, importiert im WhatsApp Manager erstellte Vorlagen und aktualisiert den Genehmigungsstatus. Mit **Add template** erstellst du einen eigenen Entwurf oder durchsuchst die offizielle Vorlagenbibliothek nach Sprache, mit Live-Telefonvorschau. Variablen müssen fortlaufend nummeriert sein (`{{1}}`, `{{2}}`, `{{3}}`) und einer Systemvariable, einem Lead-Attribut, einer Assistentenvariable oder einem eigenen Schlüssel zugeordnet werden. URL- und Telefonnummer-Buttons müssen konfiguriert sein, bevor eine Vorlage aus der Bibliothek hinzugefügt wird. 6. Einen Test-WhatsApp-Anruf über das Verbindungspanel durchführen Kopiere für die manuelle Einrichtung die nach dem Verbinden angezeigte Webhook-URL (verifizierte Custom Domains werden automatisch gehandhabt) und abonniere **messages**, **calls** und **message template status updates**. Aktiviere für Voice zusätzlich Calling auf der Telefonnummer unter **Edit → Enable calling on Meta**. ## Das 24-Stunden-Fenster und Vorlagen Meta erlaubt Freitext-Antworten nur innerhalb eines **24-hour service window**, das sich jedes Mal öffnet, wenn dir ein Kunde schreibt: * **Innerhalb des Fensters** – dein Assistent kann jede Nachricht senden, keine Vorlage nötig. * **Außerhalb des Fensters** – du musst eine **genehmigte Vorlage** senden. Das gilt für den Start einer neuen Konversation, die Reaktivierung eines Kunden nach 24 Stunden Inaktivität sowie jede von dir initiierte Benachrichtigungs- oder Marketing-Nachricht. Meta sortiert Vorlagen in drei Kategorien, jede mit einer eigenen Genehmigungshürde: | Kategorie | Verwendung für | Typische Genehmigungsdauer | | ------------------ | -------------------------------------------------------------------------------------------- | -------------------------- | | **Utility** | Bestell-/Terminbestätigungen, Erinnerungen, Konto-Benachrichtigungen – nie werbliche Inhalte | Minuten bis wenige Stunden | | **Marketing** | Angebote, Ankündigungen, Reaktivierung | Stunden, bis zu 24 Stunden | | **Authentication** | Einmalpasswörter, Login-/Verifizierungscodes | Minuten bis wenige Stunden | **Add template** erstellt Utility- und Marketing-Vorlagen, und die offizielle Bibliothek, die es durchsucht, ist Utility. Authentication- Vorlagen werden im WhatsApp Manager erstellt und von **Sync with Meta** wie jede andere Vorlage übernommen. Eine **call-permission request** ist keine eigene Kategorie – sie ist eine `CALL_PERMISSION_REQUEST`-Button-Komponente, die einer Utility- oder Marketing-Vorlage hinzugefügt wird, um einen Kunden um die Erlaubnis zu bitten, ihn über WhatsApp Voice anzurufen. Die Genehmigung dieser Komponente erfolgt meist sofort. Meta lehnt Vorlagen ab, die Kategorien vermischen – zum Beispiel werbliche Sprache innerhalb einer Utility-Vorlage. Weitere häufige Ablehnungsgründe: vage Beispielwerte für `{{1}}`/`{{2}}`-Variablen (nutze realistische Beispiele, nicht „test“), aggressive oder dringlich klingende Sprache, URL-Shortener statt der eigenen Domain sowie eingeschränkte Inhalte (Alkohol, Glücksspiel, Erwachseneninhalte, politische oder anderweitig verbotene Kategorien). Ist eine Vorlage einmal genehmigt, lässt sie sich nicht mehr bearbeiten – erstelle stattdessen eine neue. Halte für Use Cases mit hohem Volumen ein paar Ersatzvorlagen bereit, damit eine einzelne Ablehnung oder Deaktivierung deine Kommunikation nicht blockiert. ## Nachrichtenqualität und Sendelimits Meta steuert über zwei getrennte Größen, wie viel ein Sender senden darf. **Quality rating** – **High**, **Medium** oder **Low**, je nachdem, wie Menschen auf deine Nachrichten reagieren: Blockierungen, Spam-Meldungen und ob sie antworten. Sie sinkt nach einer Serie von Blockierungen oder Meldungen und erholt sich, wenn du relevante, angeforderte Inhalte sendest. **Messaging limit** – wie viele Kunden du innerhalb von 24 gleitenden Stunden neu kontaktieren darfst. Ein neuer Sender startet auf der niedrigsten Stufe (typischerweise 250 Kunden), und Meta hebt sie Schritt für Schritt an – 1.000, dann 10.000, dann 100.000, dann unbegrenzt –, sobald du mehr bei gesunder Quality Rating sendest. Eine dauerhaft niedrige (Low) Bewertung kann die Stufe einfrieren oder wieder herabsetzen. Antworten innerhalb eines offenen 24-Stunden-Fensters zählen nicht auf das Limit. Beide Werte kommen direkt von Meta und werden pro Sender unter **Edit → WhatsApp Sender Details** als **Quality Rating** und **Messaging Limit** angezeigt – baue dir also erst eine Historie qualitativ guter Konversationen auf, bevor du das Volumen hochskalierst. ## Kampagnen Wähle **WhatsApp** im Kampagnen-Wizard, um pro Lead einmal die genehmigte Text-Vorlage eines aktiven Senders zu senden. Gespeicherte Vorlagen-Bindings sind vorausgefüllt und lassen sich pro Kampagne überschreiben. Mappings können kanonische Kontaktfelder, schreibgeschützte Kanal-/Systemvariablen, Lead-Attribute, Assistentenvariablen oder einen eigenen Lead-Schlüssel nutzen. **WhatsApp Call (Beta)** erfordert Beta Features, WhatsApp-Voice-Zugang, einen outbound-fähigen Sender sowie eine für diesen Sender ausgewählte, genehmigte Call-Permission-Vorlage. Von Unternehmen initiierte Anrufe hängen zudem von der Verfügbarkeit bei Meta, der Region und der ausdrücklichen Erlaubnis des Kunden ab. Berechtigungsanfragen und ihr sichtbarer Status **Awaiting permission** werden automatisch verwaltet. Eine erteilte Erlaubnis setzt den Lead nur fort, solange seine Kampagne läuft. Voice-Kampagnen können eine genehmigte WhatsApp-Vorlage, SMS oder E-Mail als ihr einziges Follow-up nach den Wiederholungsversuchen nutzen. Erfolgreiche Anrufe, gesperrte Kontakte und manuell pausierte Kampagnen erzeugen dieses Follow-up nie. Vorlagen-Versand nutzt dieselben Messaging-Credits wie WhatsApp innerhalb einer Session. ## Read-Receipts-Webhook In **WhatsApp Sender Details** kannst du einen HTTPS-Endpunkt konfigurieren, der Zustell- und Lesestatus-Callbacks empfängt. Jeder Callback wird mit HMAC-SHA256 über den exakten rohen Request-Body signiert. Die Signatur wird als `X-Signature-256: sha256=` gesendet. Ein Signing Secret wird erzeugt, sobald du die Webhook-URL zum ersten Mal speicherst. Bestehende Secrets lassen sich nicht erneut abrufen. Nutze **Rotate signing secret** in den Sender-Einstellungen, `POST /api/v1/whatsapp/connectors/{id}/profile` mit `action=rotate_read_receipts_webhook_secret`, oder das MCP-Tool `rotate_whatsapp_read_receipts_webhook_secret`. Das neue `signing_secret` wird genau einmal angezeigt oder zurückgegeben, und das vorherige Secret funktioniert sofort nicht mehr. Sichere den neuen Wert, bevor du die Antwort verlässt, und aktualisiere deinen Empfänger, bevor du eine Testanfrage sendest. ## Verlauf Jede WhatsApp-Konversation landet neben deinen anderen Kanälen in [Verlauf](/de/monitoring/history): * Textkonversationen erscheinen als Kanal **WhatsApp**. * Voice-Anrufe erscheinen als Kanal **WhatsApp voice**. Abgeschlossene Textkonversationen bleiben manuell beantwortbar, solange Metas 24-Stunden-Servicefenster offen ist. Nach einer manuellen Antwort fragt History, ob die Konversation abgeschlossen bleiben oder mit KI-Auto-Antworten wieder geöffnet werden soll. Das Wiederöffnen startet einen neuen Inaktivitäts-Timer, ohne Metas 24-Stunden-Fenster zu verlängern. Sendet ein Kunde ein Foto, beschreibt dein Assistent automatisch, was darauf zu sehen ist, und kann als Teil der Konversation darauf eingehen. Eingehende Sprachnachrichten werden automatisch transkribiert und wie eine getippte Nachricht behandelt. Sowohl das Medium als auch die resultierende Beschreibung oder das Transkript sind in der Konversation sichtbar. ## Abrechnung * Text: wird pro Nachricht abgerechnet, zum **Messaging (sent)**- / **Messaging (received)**-Tarif deines Workspace – demselben Tarif, den auch [andere Messaging-Kanäle](/de/channels/messaging#abrechnung) nutzen. Aktuelle Tarife findest du auf der [Usage-Seite](https://app.famulor.io/usage). * Voice: bestehende Reservierung/Abrechnung von Sprachminuten-Credits (wie bei Telefon-/SIP-Anrufen) * Meta-Konversationspreise: Zahlungsmethode des Kunden im WhatsApp Manager (Tech Provider) ## Fehlerbehebung Das Status-Pill eines Senders zeigt **PENDING**, **CONNECTED** oder **ERROR**. Stelle sicher, dass du das gesamte Meta-Signup-Popup durchlaufen und während der Einrichtung einen WhatsApp-Business-Account neu erstellt (nicht wiederverwendet) hast, und aktualisiere nach ein paar Minuten. Ist er nach mehr als 30 Minuten immer noch PENDING: Support mit der Sender-ID kontaktieren. Öffne **Edit** und lies den letzten Fehler. Probleme mit Zugangsdaten behebst du, indem du den Connect-Flow erneut durchläufst; eine Policy- oder Qualitätssperre muss adressiert (meist spamartiges Sendeverhalten) und über Meta angefochten werden. Die obigen Ablehnungsgründe sind die üblichen Ursachen; eine deaktivierte Vorlage ist normalerweise Qualitäts-Feedback. Erstelle eine verbesserte Version und grenze ein, an wen du sie sendest. Marketing-Vorlagen können am längsten dauern; erstelle eine alternative Vorlage, wenn du früher senden musst. Sende an Nummern im E.164-Format, bestätige, dass der Empfänger WhatsApp hat, prüfe, dass der Sender CONNECTED ist, und stelle sicher, dass du dein Messaging Limit nicht erreicht hast. Du bist außerhalb des 24-Stunden-Fensters des Kunden; sende stattdessen eine genehmigte Vorlage. Stelle sicher, dass dem Sender ein Assistent zugewiesen und **AI Auto-Responses** aktiviert ist, und prüfe dann in History den Fehlerstatus der Konversation. Prüfe, was du unmittelbar vor dem Abfall gesendet hast, schärfe das Targeting und reduziere das Volumen; sowohl die Bewertung als auch die Stufe erholen sich, wenn du hochwertigere, relevantere Nachrichten sendest. Erlaube Popups für die Seite, lösche Cookies/Cache, oder versuche es in einem anderen Browser; starte den Connect-Flow danach von vorn. ## Public API * Messaging Connectors: `GET/POST /api/v1/messaging-connectors` mit `platform=whatsapp` * Vorlagen: `GET/POST /api/v1/whatsapp/templates`; nutze `source=library`, `language`, `limit` und den zurückgegebenen `paging.after`-Cursor, um die offizielle Bibliothek zu durchsuchen. `parameter_bindings` ordnet Positionen wie `1` oder `header.1` Variablenschlüsseln zu. Übergib `library_template_name` plus `library_button_values`, wenn eine Vorlage URL- oder Telefonnummer-Buttons hat. `action=update` bearbeitet Entwürfe lokal oder sendet Komponentenänderungen für eine bestehende Anbieter-Vorlage. API- und MCP-Clients können dieselbe Call-Permission-Vorlage erstellen, indem sie eine `BODY`- und `CALL_PERMISSION_REQUEST`-Komponente übergeben. * Outbound Voice: `POST /api/v1/calls/whatsapp-outbound` * History-KI-Fortsetzung: `POST /api/v1/history/actions` mit `action=resume_ai`, `kind=messaging` und der Conversation-ID * Calling-Verwaltung: `GET /api/v1/whatsapp/calling` liest die Anruf-Bereitschaft (Meta-Anrufeinstellungen, Webhook-Abonnement, Quality Rating) für die Business-Nummer eines Connectors; `POST /api/v1/whatsapp/calling` führt `enable_calling`, `resubscribe` oder `ensure_voice` aus. * Sender-Assets: `POST`/`DELETE /api/v1/whatsapp/connectors/{id}/assets` lädt ein Business-Profil-Logo/-Banner hoch oder entfernt es (URL oder Base64). * Sender-Profil und Read Receipts: `GET`/`PATCH`/`POST /api/v1/whatsapp/connectors/{id}/profile` verwaltet das Sender-Profil, testet den signierten Callback und rotiert dessen Signing Secret. * Messenger Connect lässt sich auch vollständig über die API steuern: `POST /api/v1/messenger/facebook-login/pages` listet die Facebook-Pages auf, die ein User Access Token verwalten kann, vor `POST /api/v1/messenger/facebook-login`. * MCP: WhatsApp-Template-Tools + `start_whatsapp_outbound_call` + `get_whatsapp_calling_status` + `manage_whatsapp_calling` + `rotate_whatsapp_read_receipts_webhook_secret` + `upload_whatsapp_sender_asset` / `delete_whatsapp_sender_asset` + `list_messenger_facebook_pages` Die **OTP capture**-Session für Marketplace-Nummern (der Telefonnummer-Verifizierungsschritt, der eine gekaufte Nummer WhatsApp-fähig macht) bleibt ausschließlich im Dashboard – es handelt sich um einen interaktiven Telefonie-Ablauf ohne REST-/MCP-Äquivalent. Siehe auch [Embedded Signup setup](/de/channels/whatsapp-embedded-signup), [Messaging-Kanäle](/de/channels/messaging), [WhatsApp Voice](/de/telephony/whatsapp-voice).