WhatsApp API: Nachrichten senden (Python, PHP & Node.js Guide)

Die WhatsApp Cloud API hat ein Dokumentationsproblem. Nicht weil die Infos fehlen – sondern weil sie über 47 Unterseiten verstreut sind, sich gegenseitig widersprechen und das Wichtigste (wie du einen Token bekommst, der länger als 24 Stunden hält) irgendwo im Business Manager versteckt ist.

Dieser Guide ist das Gegenteil: Ein Dokument. Alles drin. Funktionierender Code für Python, Node.js und PHP. Die Pricing-Hacks für 2026. Und die eine Sache, die Meta dir nicht auf der Startseite zeigt – aber die dich sofort sperren kann, wenn du sie ignorierst.

Das Wichtigste in Kürze

Endpoint: Alle Nachrichten gehen über POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages

Authentifizierung: Du brauchst einen permanenten Access Token (via System User im Business Manager) – der temporäre Token läuft nach 24h ab

24-Stunden-Regel: Freitext-Nachrichten nur innerhalb von 24h nach letzter Kundenantwort möglich, danach nur noch Templates

Kosten-Hack: Utility-Templates sind kostenlos, wenn sie innerhalb des offenen 24h-Fensters gesendet werden

Messaging Limits: Neue Nummern starten bei 250 msg/24h – Skalierung auf unbegrenzt durch Business-Verifizierung und hohe Qualität

AI-Policy 2026: "General Purpose AI"-Bots sind seit Januar 2026 verboten, aufgabenbezogene Bots (Support, Sales) bleiben erlaubt

Interaktive Nachrichten: Reply Buttons (max. 3) und List Messages (max. 10 Optionen) erhöhen die Conversion deutlich

Die Basics: Was du wirklich brauchst

Bevor du eine einzige Zeile Code schreibst, brauchst du vier Dinge:

Meta Developer Account – Kostenlos unter developers.facebook.com

WhatsApp Business Account (WABA) – Wird beim App-Setup automatisch erstellt

Verifizierte Telefonnummer – Darf nicht bereits für WhatsApp privat genutzt werden

Permanenter Access Token – Hier scheitern 80% der Entwickler beim ersten Versuch

Die ersten drei sind Klick-Klick-fertig. Der Token ist es nicht.

Permanenten Access Token erstellen (Schritt-für-Schritt)

Der temporäre Token aus dem API-Setup hält 24 Stunden. Danach ist dein Bot tot. Für Produktion brauchst du einen System User Token ohne Ablaufdatum.

So geht's:

Öffne den Meta Business Manager

Gehe zu Unternehmenseinstellungen → Nutzer → Systemnutzer

Klicke auf Hinzufügen und erstelle einen neuen Systemnutzer mit der Rolle Admin

Wähle den erstellten Nutzer aus und klicke auf Assets zuweisen

Wähle unter "Apps" deine WhatsApp-App und vergib Vollständige Kontrolle

Klicke auf Token generieren

Wähle diese Berechtigungen:

whatsapp_business_messaging

whatsapp_business_management

Kopiere den Token – er wird nur einmal angezeigt

Dieser Token läuft nie ab. Behandle ihn wie ein Passwort: Niemals im Frontend, niemals im Git-Repository, immer als Environment Variable.

Der Messages-Endpoint

Alle Nachrichten – Text, Bilder, Dokumente, Buttons – gehen über einen einzigen Endpoint:

POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages

Die aktuelle API-Version ist v21.0 (Stand: Februar 2026). Deine PHONE_NUMBER_ID findest du im Meta Developer Dashboard unter WhatsApp → API Setup.

Authentifizierung

Authorization: Bearer {DEIN_PERMANENTER_TOKEN}
Content-Type: application/json

Session-Nachrichten vs. Template-Nachrichten

Hier liegt der größte Stolperstein für Entwickler. WhatsApp unterscheidet strikt:

Session-Nachrichten kannst du nur senden, wenn der Kunde dir innerhalb der letzten 24 Stunden geschrieben hat. Innerhalb dieses Fensters ist alles erlaubt: Freitext, Bilder, Dokumente, Buttons.

Template-Nachrichten sind vordefinierte Vorlagen, die Meta vorher genehmigen muss (24–48h Wartezeit). Nur damit kannst du Kunden außerhalb des 24h-Fensters kontaktieren.

Der Utility-Hack für 2026

Hier wird's spannend: Utility-Templates (Bestellbestätigungen, Versandupdates, Terminerinnerungen) sind kostenlos, wenn du sie innerhalb eines offenen 24h-Fensters sendest.

Das bedeutet: Kunde schreibt dir → Du antwortest mit einem Utility-Template statt Freitext → Kostenlos statt kostenpflichtig.

Klingt wie ein kleines Detail? Bei 10.000 Nachrichten pro Monat spart das je nach Region mehrere hundert Euro. Die genaue Kostenstruktur erklärt unser WhatsApp API Pricing Guide im Detail.

Code-Beispiele: Textnachricht senden

cURL (zum Testen)

curl -X POST "https://graph.facebook.com/v21.0/PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "4917612345678",
"type": "text",
"text": {
"preview_url": false,
"body": "Deine Bestellung #12345 ist unterwegs!"
}
}'

Die Telefonnummer muss im E.164-Format sein: Ländercode ohne +, keine Leerzeichen, keine führende Null (also 4917612345678, nicht +49 176 12345678).

Python

import requests
import os

def send_whatsapp_message(phone_number: str, message: str) -> dict:
"""
Sendet eine WhatsApp-Textnachricht über die Cloud API.

Args:
phone_number: Empfänger im Format 4917612345678
message: Der Nachrichtentext (max. 4096 Zeichen)

Returns:
API-Response mit message_id bei Erfolg
"""
url = f"https://graph.facebook.com/v21.0/{os.environ['WA_PHONE_NUMBER_ID']}/messages"

headers = {
"Authorization": f"Bearer {os.environ['WA_ACCESS_TOKEN']}",
"Content-Type": "application/json"
}

payload = {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": phone_number,
"type": "text",
"text": {
"preview_url": False,
"body": message
}
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()  # Wirft Exception bei 4xx/5xx
return response.json()

# Beispiel
result = send_whatsapp_message("4917612345678", "Deine Bestellung ist unterwegs!")
print(f"Nachricht gesendet: {result['messages'][0]['id']}")

Node.js

const axios = require('axios');

async function sendWhatsAppMessage(phoneNumber, message) {
const url = `https://graph.facebook.com/v21.0/${process.env.WA_PHONE_NUMBER_ID}/messages`;

const payload = {
messaging_product: 'whatsapp',
recipient_type: 'individual',
to: phoneNumber,
type: 'text',
text: {
preview_url: false,
body: message
}
};

const response = await axios.post(url, payload, {
headers: {
'Authorization': `Bearer ${process.env.WA_ACCESS_TOKEN}`,
'Content-Type': 'application/json'
}
});

return response.data;
}

// Beispiel
sendWhatsAppMessage('4917612345678', 'Deine Bestellung ist unterwegs!')
.then(res => console.log('Gesendet:', res.messages[0].id))
.catch(err => console.error('Fehler:', err.response?.data || err.message));

PHP

<?php

function sendWhatsAppMessage(string $phoneNumber, string $message): array
{
$url = 'https://graph.facebook.com/v21.0/' . getenv('WA_PHONE_NUMBER_ID') . '/messages';

$payload = [
'messaging_product' => 'whatsapp',
'recipient_type' => 'individual',
'to' => $phoneNumber,
'type' => 'text',
'text' => [
'preview_url' => false,
'body' => $message
]
];

$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WA_ACCESS_TOKEN'),
'Content-Type: application/json'
],
CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode >= 400) {
throw new Exception("API Error: $response");
}

return json_decode($response, true);
}

// Beispiel
$result = sendWhatsAppMessage('4917612345678', 'Deine Bestellung ist unterwegs!');
echo "Gesendet: " . $result['messages'][0]['id'];

Interaktive Nachrichten: Buttons & Listen

Hier wird's interessant. Buttons erhöhen die Interaktionsrate massiv – Nutzer tippen lieber auf einen Button als eine Antwort zu formulieren. WhatsApp bietet zwei Typen:

Reply Buttons (max. 3 Buttons)

payload = {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "4917612345678",
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "Bestellstatus"
},
"body": {
"text": "Deine Bestellung #12345 ist in Zustellung. Was möchtest du tun?"
},
"footer": {
"text": "Powered by Chatarmin"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "track_order",
"title": "📍 Sendung verfolgen"
}
},
{
"type": "reply",
"reply": {
"id": "contact_support",
"title": "💬 Support kontaktieren"
}
},
{
"type": "reply",
"reply": {
"id": "change_address",
"title": "📝 Adresse ändern"
}
}
]
}
}
}

List Messages (max. 10 Optionen)

Perfekt für Auswahlmenüs mit mehr Optionen:

payload = {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "4917612345678",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "Hilfe & Support"
},
"body": {
"text": "Wie können wir dir helfen? Wähle ein Thema:"
},
"action": {
"button": "Thema wählen",
"sections": [
{
"title": "Bestellung",
"rows": [
{"id": "order_status", "title": "Bestellstatus", "description": "Wo ist mein Paket?"},
{"id": "order_cancel", "title": "Stornierung", "description": "Bestellung abbrechen"},
{"id": "order_return", "title": "Retoure", "description": "Artikel zurücksenden"}
]
},
{
"title": "Produkte",
"rows": [
{"id": "product_info", "title": "Produktberatung", "description": "Hilfe bei der Auswahl"},
{"id": "product_stock", "title": "Verfügbarkeit", "description": "Ist Artikel X auf Lager?"}
]
}
]
}
}
}

Die Button-ID (track_order, order_status etc.) bekommst du als Webhook-Payload zurück, wenn der Nutzer klickt. Damit steuerst du deinen Bot-Flow. Wie du Webhooks aufsetzt und die Antworten verarbeitest, zeigt unser Chatbot API Guide.

Template-Nachricht senden

Für Nachrichten außerhalb des 24h-Fensters brauchst du ein genehmigtes Template:

payload = {
"messaging_product": "whatsapp",
"to": "4917612345678",
"type": "template",
"template": {
"name": "order_shipped",
"language": {
"code": "de"
},
"components": [
{
"type": "body",
"parameters": [
{"type": "text", "text": "Max"},           # {{1}} = Kundenname
{"type": "text", "text": "12345"},         # {{2}} = Bestellnummer
{"type": "text", "text": "DHL Express"}    # {{3}} = Versandart
]
}
]
}
}

Templates erstellst du im WhatsApp Manager unter Account Tools → Message Templates. Rechne mit 24–48 Stunden Prüfzeit durch Meta.

Messaging Limits: Warum deine Nachrichten plötzlich stoppen

Neue WhatsApp Business Nummern starten mit einem Limit von 250 Nachrichten pro 24 Stunden. Das reicht für Tests – aber nicht für Produktion.

So skalierst du:

Die Qualitätsbewertung siehst du im WhatsApp Manager unter Phone Numbers → Quality Rating. Sinkt sie auf "Low", wird dein Limit automatisch reduziert oder die Nummer gesperrt.

AI-Policy 2026: Was du wissen musst

Achtung: Seit dem 15. Januar 2026 untersagt Meta sogenannte "General Purpose AI Assistants" auf WhatsApp. Das betrifft offene ChatGPT-Wrapper ohne klaren Geschäftszweck – also Bots, die auf jede beliebige Frage antworten.

Erlaubt sind aufgabenbezogene Bots mit definiertem Scope:

Kundenservice-Bots (FAQ, Ticketstatus)

Sales-Bots (Produktberatung, Bestellungen)

Termin-Bots (Buchungen, Erinnerungen)

Verboten sind:

"Frag mich alles"-Bots ohne Business-Kontext

Bots, die sich als menschliche Mitarbeiter ausgeben

Bei Chatarmin setzen wir genau auf diese Compliance: Jeder Bot hat einen klaren Zweck, definierte Flows und transparente Bot-Kennzeichnung. Unser WhatsApp Automation Guide zeigt, wie das in der Praxis aussieht.

Fehlerbehandlung: Die häufigsten Error-Codes

Bei persistenten Fehlern: WhatsApp Manager → Insights → Logs prüfen.

Praxis: So nutzen Unternehmen die API

Die Code-Snippets oben sind der Anfang. In der Praxis steht dahinter ein System, das automatisiert entscheidet: Welche Nachricht? An wen? Wann? Mit welchem Template?

Waterdrop verarbeitet tausende WhatsApp-Anfragen täglich – automatisierte Erstantworten, intelligentes Routing an die richtigen Teams, Eskalation bei komplexen Fällen.

Luxusbetten24 nutzt die API für die komplette Customer Journey: Bestellbestätigung → Versandupdate → Lieferankündigung → Bewertungsanfrage. Alles automatisiert, alles messbar.

Cusbclo zeigt, wie Welcome-Flows funktionieren: Neukunde schreibt → automatische Begrüßung mit Buttons → Qualifizierungsfragen → direktes Routing zum passenden Produkt.

Build vs. Buy: Eine ehrliche Einschätzung

Du kannst alles selbst bauen. Server aufsetzen, Webhooks konfigurieren, Retry-Logik für fehlgeschlagene Nachrichten, Status-Tracking, Template-Verwaltung mit Meta-Sync, DSGVO-konforme Opt-in-Dokumentation.

Realistisch: Das sind 3–6 Monate Entwicklungszeit für ein Team, das es zum ersten Mal macht. Plus laufende Wartung bei API-Updates (Meta released ca. alle 3 Monate eine neue Version).

Bei Chatarmin lösen wir genau das: Die technische Komplexität verschwindet hinter einem UI. Flow Builder statt Code für jeden Nachrichtentyp. Template-Management mit direkter Meta-Anbindung. Analytics, die zeigen, welche Nachrichten konvertieren und welche nicht.

Das heißt nicht, dass API-Wissen unnütz ist – im Gegenteil. Wer versteht, was unter der Haube passiert, trifft bessere Entscheidungen. Aber zwischen "verstehen" und "selbst warten müssen" liegt ein erheblicher Unterschied an Zeit und Budget.

FAQ: Die 10 häufigsten Fragen

Ist die WhatsApp Business API kostenlos?

Die API selbst hat keine Grundgebühr, aber Meta berechnet Kosten pro Unterhaltung (Conversation-Based Pricing). Die ersten 1.000 Service-Unterhaltungen pro Monat sind kostenlos.

Was ist der Unterschied zwischen Cloud API und On-Premise API?

Die Cloud API wird von Meta gehostet und skaliert automatisch. Die On-Premise API muss auf eigenen Servern (Docker) betrieben werden. Für 99% der Unternehmen ist die Cloud API 2026 der Standard – Meta selbst empfiehlt die Migration.

Wie bekomme ich einen permanenten Access Token?

Im Meta Business Manager unter Systemnutzer: Neuen Admin-User erstellen, App zuweisen, Token mit den Berechtigungen whatsapp_business_messaging und whatsapp_business_management generieren. Dieser Token läuft nicht ab.

Was sind WhatsApp Messaging Limits?

Neue Nummern starten mit 250 oder 1.000 Nachrichten pro 24 Stunden. Durch Business-Verifizierung und hohe Qualitätsbewertungen skaliert das Limit automatisch auf 10k, 100k oder unbegrenzt.

Sind KI-Chatbots auf WhatsApp erlaubt?

Ja, solange sie einen klaren Geschäftszweck haben (Support, Sales, Booking). Seit Januar 2026 sind reine "General Purpose AI"-Bots ohne spezifischen Fokus laut Meta-Richtlinien untersagt.

Kann ich WhatsApp Newsletter ohne Opt-in versenden?

Nein. Das führt zur sofortigen Sperrung der Nummer. Jeder Empfänger muss dem Erhalt von Nachrichten explizit zugestimmt haben – dokumentiert und DSGVO-konform.

Was kostet eine WhatsApp Business Nachricht 2026?

Die Kosten variieren nach Land und Kategorie. Marketing-Nachrichten nach Deutschland kosten ca. 0,14 €, Utility-Nachrichten ca. 0,08 €. Service-Antworten innerhalb des 24h-Fensters sind kostenlos.

Was passiert, wenn das 24-Stunden-Fenster abläuft?

Du kannst keine Freitext-Nachrichten mehr senden. Um die Konversation wieder zu eröffnen, brauchst du ein genehmigtes Template – das kostet dann je nach Kategorie.

Brauche ich eine eigene Telefonnummer für die API?

Ja. Die Nummer darf nicht gleichzeitig mit der privaten WhatsApp App oder der WhatsApp Business App auf einem Handy verknüpft sein. Eine Nummer = ein Kanal.

Warum werden meine Templates abgelehnt?

Häufigste Gründe: Werbliche Inhalte in Utility-Templates, fehlende Variablen-Beispiele, Verstoß gegen Handelsrichtlinien (z.B. Alkohol, Tabak), oder der Template-Name enthält Sonderzeichen.

Fazit

Die WhatsApp Cloud API ist technisch nicht kompliziert – ein POST-Request, JSON-Payload, fertig. Die Komplexität liegt woanders: Im Token-Management, im 24h-Fenster, in den Messaging Limits, in der Template-Freigabe, in der AI-Policy.

Für einen schnellen Test reichen die Code-Snippets oben. Für Produktion mit tausenden Kunden brauchst du mehr: Monitoring, Fehlerbehandlung, Compliance-Checks, Retry-Logik.

Nächster Schritt: Teste die API mit deiner Testnummer im Meta Developer Dashboard. Wenn die erste Nachricht ankommt, entscheide: Selbst bauen oder fertig kaufen?