· 6 min · TextMeFlow Team

WhatsApp API mit cURL und Postman testen – vor dem Livegang

Die meisten Integrationsfehler zeigen sich erst, wenn der Code längst in einem Formular-Handler, einem CRM-Webhook oder einem Cronjob steckt – und dann sind sie mühsam einzugrenzen. Die Lösung: Teste die API zuerst für sich allein, nur mit einem Terminal, bevor dieser Code überhaupt existiert. Fünfzehn Minuten mit cURL (oder Postman, wenn du eine grafische Oberfläche bevorzugst) decken die drei Ursachen auf, die fast jedes „Es funktioniert nicht"-Ticket auslösen: eine Nummer im falschen Format, eine WhatsApp-Sitzung, die gar nicht wirklich gekoppelt ist, und ein Missverständnis darüber, was eine 202-Antwort im Vergleich zu einer 429 tatsächlich bedeutet.

Hier gehen wir diese Abfolge Schritt für Schritt mit der TextMeFlow API durch.

API-Schlüssel holen und Konto prüfen

Jedes Konto erhält bei der Anmeldung einen API-Schlüssel der Form tmf_<your_api_key>. Bevor du etwas sendest, prüfe, ob der Schlüssel funktioniert, und sieh dir deinen aktuellen Tarif und Verbrauch an:

curl -s https://api.textmeflow.eu/v1/accounts/me \
  -H "Authorization: Bearer tmf_your_api_key_here"

Ein 200 mit deinem Konto-JSON bedeutet, dass der Schlüssel gültig ist. Ein 401 heißt, dass du ihn falsch kopiert hast oder er zu einer anderen Umgebung gehört – kläre das, bevor du irgendetwas weiter hinten debuggst. Nutzt du Postman, lege {{api_key}} als Collection-Variable an und verwende sie im Authorization-Header jeder Anfrage, statt den Schlüssel in jede Anfrage einzufügen.

Prüfen, ob WhatsApp wirklich gekoppelt ist

Ein gültiger API-Schlüssel heißt nicht, dass WhatsApp verbunden ist. TextMeFlow verbindet sich über eine QR-Code-Kopplung mit einem echten WhatsApp-Konto, und Nachrichten, die vor der Kopplung (oder nach dem Abbruch einer Sitzung) gesendet werden, schlagen fehl, auch wenn die Anfrage selbst korrekt aufgebaut ist. Prüfe den Kopplungsstatus, bevor du das Senden testest:

curl -s https://api.textmeflow.eu/v1/accounts/me \
  -H "Authorization: Bearer tmf_your_api_key_here" | jq '.session_status // .status'

Ist der Status nicht „connected", koppelst du zuerst (POST /v1/accounts/me/pair liefert einen QR-Code zum Scannen) und fragst dann /v1/accounts/me/pair/{pair_id}/status ab, bis der Status auf connected springt. Dieser übersprungene Schritt ist der häufigste Grund, warum eine „funktionierende" Integration plötzlich nichts mehr sendet – meist, weil das gekoppelte Handy offline ging oder jemand die WhatsApp-Sitzung woanders abgemeldet hat.

Eine echte Testnachricht senden

Mit gültigem Schlüssel und aktiver Sitzung sendest du zuerst eine Nachricht an deine eigene Nummer – nicht an einen Kunden:

curl -s -X POST https://api.textmeflow.eu/v1/messages \
  -H "Authorization: Bearer tmf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+32472000000",
    "text": "Testnachricht von der API – bitte ignorieren"
  }'

Ein erfolgreicher Aufruf liefert 202 Accepted mit einer message_id und status: "queued" – nicht "sent". Dieser Unterschied ist wichtig: 202 bedeutet, dass die API den Auftrag in die Sendewarteschlange aufgenommen hat, nicht, dass WhatsApp die Nachricht schon zugestellt hat. Speichere die message_id und frage sie ein paar Sekunden später ab:

curl -s https://api.textmeflow.eu/v1/messages/<message_id> \
  -H "Authorization: Bearer tmf_your_api_key_here"

Für einen Medientest ergänzt du ein Feld media_url, das auf ein öffentliches Bild oder PDF zeigt – Anhänge bis 100 MB funktionieren genauso, ohne separaten Endpunkt.

Die Fehler, die in Produktion auftreten, gezielt auslösen

Nur den Idealfall zu testen zeigt lediglich, dass die API funktioniert, wenn alles perfekt ist – und so sieht die Umgebung, in der dein Produktivcode läuft, nie aus. Löse die Fehlerfälle deshalb absichtlich aus, damit deine Fehlerbehandlung wirklich geübt wurde:

  • Falsches Telefonformat – sende "to": "0472000000" statt E.164 (+32...). Du solltest einen 4xx mit einer klaren Meldung bekommen, keinen stillschweigend verworfenen Versand. Sammelt dein Formular Nummern ohne Ländervorwahl, ist das der Fehler, der dir in der Praxis am häufigsten begegnet – die Lösung steht in der Anleitung zur Validierung von Telefonnummern.
  • Rate Limit – feuere zehn Anfragen in unter einer Sekunde per schneller Shell-Schleife ab. TextMeFlow erlaubt im Dauerbetrieb etwa 1 Nachricht pro Sekunde; darüber bekommst du 429 Too Many Requests. Prüfe, dass deine Integration zurückfährt und es erneut versucht, statt eng zu loopen – das Retry-Muster steht unter Rate Limits und Nachrichtenstatus behandeln.
  • Abgelaufene oder getrennte Sitzung – melde dich auf dem gekoppelten Gerät bei WhatsApp Web ab (oder rufe DELETE /v1/accounts/me/session auf) und sende erneut. Du willst sehen, welcher Fehler zurückkommt, damit dein Code dich alarmieren kann, statt tagelang stumm zu scheitern.

Testen im TextMeBot-Stil (Legacy)

Wenn du von TextMeBot migrierst, akzeptiert der Drop-in-Endpunkt GET /send.php dieselbe Query-String-Form, die dein alter Code schon nutzt:

curl "https://api.textmeflow.eu/send.php?recipient=%2B32472000000&apikey=tmf_your_api_key_here&text=Hello"

Er liefert schlichtes HTML mit Result: <b>Success</b> oder Result: <b>Failed</b> zurück, sodass jeder Code, der diese Zeichenkette per Substring-Vergleich auswertet, unverändert weiterläuft, während du den Umstieg auf /v1/messages planst. Alle Details stehen in der TextMeBot-Migrationscheckliste.

Einmal eine Postman-Collection bauen, dauerhaft wiederverwenden

Wenn dein Team mehr als einmal an dieser Integration arbeitet, lohnt es sich, diese cURL-Aufrufe in eine kleine Postman-Collection zu überführen: eine Anfrage pro Endpunkt (accounts/me, pair, messages per POST, messages/{id} per GET), der API-Schlüssel als Collection-Variable und je ein gespeichertes Beispiel für die Antwort. Neue Teammitglieder können dann in unter einer Minute prüfen, ob die Integration lebt, ohne Code zu lesen – praktisch, wenn ein Support-Ticket mit „Ist das WhatsApp-Ding down?" hereinkommt und du schnell Ja oder Nein sagen musst.

Die vollständigen Formen von Anfragen und Antworten, inklusive aller Felder und Fehlercodes, sind in der API-Referenz dokumentiert.

Verhalten sich deine Testaufrufe wie erwartet – 202 beim Senden, eine echte message_id, saubere Fehler bei falscher Eingabe –, ist es der leichte Teil, dieselben Aufrufe in deine eigentliche Anwendung einzubauen. Melde dich für den kostenlosen Tarif an und geh diese Checkliste mit deinem eigenen Konto durch, bevor du eine einzige Zeile Integrationscode schreibst.

Selbst WhatsApp-Nachrichten per API senden?

Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.

Für immer gratis