WhatsApp Cloud API bedeutet: eine Nummer, ein Token, ein Webhook. Diese Anleitung bringt dich vom leeren Meta-Konto bis zum laufenden Auto-Responder und benennt die Stolpersteine bei Templates, Fenstern und DSGVO.
Warum die Cloud API und nicht die App
Wer im DACH-Mittelstand oder in einer Agentur WhatsApp als Kanal ernst nimmt, steht früher oder später vor der Wahl: die WhatsApp Business App auf einem Smartphone oder die WhatsApp Cloud API von Meta. Die App hängt an einem Gerät, skaliert nicht und kennt keine Automation. Die Cloud API ist der offizielle, von Meta selbst gehostete Weg, WhatsApp programmatisch zu betreiben. Du brauchst dafür eine Nummer, ein Access Token und einen Webhook.
Der Reiz: kein eigener Server für die Messaging-Infrastruktur, keine monatliche Grundgebühr an einen Zwischenanbieter (Business Solution Provider), du zahlst nur pro Konversation direkt an Meta. Dieser Artikel führt dich vom leeren Meta-Konto bis zur ersten automatisierten Antwort und benennt die Stolpersteine, die dich sonst einen Nachmittag kosten.
Voraussetzungen und die Konten-Hierarchie
Bevor die erste Nachricht rausgeht, brauchst du drei Ebenen bei Meta, und ihre Verschachtelung ist die häufigste Fehlerquelle. Ganz oben steht der Meta Business Account (business.facebook.com). Darin lebt der WhatsApp Business Account (kurz WABA), und an der WABA hängt deine Telefonnummer mit einer eigenen Phone Number ID. Parallel dazu legst du unter developers.facebook.com eine Meta App vom Typ Business an und fügst ihr das Produkt WhatsApp hinzu.
Für den Start bekommst du gratis eine Meta-Testnummer, mit der du an bis zu fünf verifizierte Empfänger senden darfst. Für den Produktivbetrieb bringst du eine eigene Nummer mit, die noch nie bei WhatsApp (auch nicht in der normalen App) registriert war. Fest- oder Mobilnummer ist egal, sie muss nur einen Anruf oder eine SMS empfangen können. Für höhere Sendevolumen verlangt Meta die Business-Verifizierung, also einen Nachweis über Handelsregister oder Impressum. Diese Prüfung dauert oft ein bis drei Werktage, also früh anstoßen.
Vom 24-Stunden-Token zum permanenten Zugang
Im App-Dashboard siehst du sofort ein temporäres Access Token. Es ist praktisch für den ersten Test, verfällt aber nach 24 Stunden. Für alles Dauerhafte legst du im Business Manager unter Einstellungen einen System-User an, weist ihm deine App zu und erzeugst ein Token mit den Berechtigungen whatsapp_business_messaging und whatsapp_business_management. Dieses Token läuft nicht ab und gehört in einen Secret-Store, nicht ins Git-Repo.
Die Nummer selbst musst du einmalig aktivieren. Dabei setzt du eine sechsstellige PIN für die Zwei-Faktor-Registrierung, entweder in der Oberfläche oder per API:
POST /v21.0/
Merke dir diese PIN. Meta fragt sie bei einem späteren Umzug der Nummer wieder ab.
Die erste Nachricht und das 24-Stunden-Fenster
Alle Nachrichten laufen über einen einzigen Endpunkt: POST https://graph.facebook.com/v21.0/. Das schnellste Erfolgserlebnis ist die vordefinierte Vorlage hello_world:
curl -X POST 'https://graph.facebook.com/v21.0/
Jetzt die wichtigste Regel des ganzen Kanals: das 24-Stunden-Servicefenster. Schreibt dir ein Kontakt, darfst du ihm 24 Stunden lang beliebige freie Nachrichten (Text, Bilder, Buttons) senden. Sobald das Fenster zu ist, gehen nur noch genehmigte Vorlagen (Templates) raus. Jede Vorlage wird von Meta geprüft und einer von drei Kategorien zugeordnet:
- Utility: transaktional, etwa Bestellbestätigung oder Terminerinnerung.
- Authentication: Einmalcodes und Logins.
- Marketing: Angebote, Reaktivierung, alles Werbliche.
Die Kategorie bestimmt den Preis und wie streng Meta prüft. Wer eine Marketing-Botschaft als Utility tarnt, kassiert eine Ablehnung oder eine Herabstufung der Qualitätsbewertung.
Webhook: eingehende Nachrichten empfangen
Senden allein ist ein Newsletter. Für echte Automation brauchst du den Rückkanal, und der läuft über einen Webhook. Du hinterlegst in der App-Konfiguration eine öffentlich erreichbare Callback-URL (HTTPS Pflicht) und ein frei gewähltes Verify-Token. Meta ruft die URL zuerst per GET auf:
GET /webhook?hub.mode=subscribe&hub.verify_token=DEIN_TOKEN&hub.challenge=12345
Stimmt das Token, antwortest du mit reinem Text und dem Wert aus hub.challenge, hier also 12345. Danach abonnierst du im Dashboard das Feld messages. Ab jetzt schickt Meta jede eingehende Nachricht als POST an deine URL. Die Nutzlast ist verschachtelt, die Nachricht selbst steckt in entry[0].changes[0].value.messages[0]. Verifiziere jede POST-Anfrage über die Signatur im Header X-Hub-Signature-256, ein HMAC-SHA256 mit deinem App Secret. Ohne diese Prüfung kann jeder deinen Endpunkt mit gefälschten Nachrichten fluten.
Die erste Automation bauen
Für den Logik-Teil brauchst du keinen dedizierten Server. Ein Cloudflare Worker oder eine kleine Funktion auf n8n, Make oder Supabase Edge Functions reicht. Der Ablauf ist immer gleich: Webhook empfängt die Nachricht, dein Code entscheidet, ein zweiter API-Call antwortet. Ein minimaler Auto-Responder in Pseudocode:
const msg = body.entry[0].changes[0].value.messages[0]; if (msg.text.body.toLowerCase().includes("preis")) { sendTemplate(msg.from, "preisliste"); }
Realistischer als ein reiner Echo-Bot ist ein Router: Neue Kontakte landen als Lead in deinem CRM (etwa über einen HubSpot- oder Supabase-Insert), Bestandskunden bekommen eine Utility-Vorlage mit Statusupdate, und alles, was der Bot nicht sicher versteht, wird an einen Menschen übergeben. Wichtig für die Antwortlogik: Prüfe immer, ob das 24-Stunden-Fenster noch offen ist. Innerhalb sendest du eine günstige freie Textnachricht, außerhalb zwingend eine Vorlage. Diese Fallunterscheidung im Code spart dir später Support-Tickets und Kosten.
Limits, Kosten und die typischen Fallen
Meta drosselt neue Nummern bewusst. Du startest im Messaging-Tier von 250 einzigartigen Empfängern pro 24 Stunden und steigst bei guter Qualitätsbewertung automatisch auf 1.000, dann 10.000 und mehr. Die Qualitätsbewertung (grün, gelb, rot) hängt daran, wie oft Empfänger blockieren oder als Spam melden. Rutschst du auf Rot, kann Meta das Senden temporär sperren. Der wirksamste Schutz ist ein sauberes, dokumentiertes Opt-in.
Bei den Kosten hat Meta 2025 auf ein Modell pro Nachricht umgestellt. Grob liegen Marketing-Vorlagen in Deutschland aktuell bei rund 6 bis 8 Cent pro Stück, Utility-Nachrichten im offenen Servicefenster sind oft kostenlos, und vom Nutzer gestartete Servicekonversationen ebenfalls. Die genauen Sätze ändern sich, prüfe vor jeder Kalkulation die aktuelle Rate Card von Meta.
Zwei Fallen zum Schluss. Erstens die DSGVO: Du brauchst ein nachweisbares Opt-in, bevor du jemanden anschreibst, ein gekaufter Nummernbestand ist tabu. Zweitens die Vorlagen-Disziplin: Reiche Templates früh ein, die Prüfung dauert Minuten bis Stunden, und ohne genehmigte Vorlage bekommst du außerhalb des Fensters keine einzige Nachricht raus. Wer diese beiden Punkte von Anfang an ernst nimmt, hat von der Nummer bis zur laufenden Automation an einem Tag alles stehen.