WhatsApp-OTP-API-Integration: Beispiele für PHP, Node.js und Python

Einen Bestätigungscode per WhatsApp zu senden, läuft mit der WapFlow-OTP-API auf zwei Aufrufe hinaus: Einer sendet den Code, der andere prüft, was der Nutzer eingegeben hat. In diesem Leitfaden sammeln wir, wie die API funktioniert, und zeigen cURL-, PHP-, Node.js- und Python-Beispiele, die Fehlerbehandlung und die Sicherheitspunkte, auf die Sie achten sollten. Die Beispiele folgen dem Format der offiziellen API-Dokumentation und enthalten nur kleine Ergänzungen zur besseren Lesbarkeit. Wenn Sie vor dem Programmieren wissen möchten, worum es bei dem Produkt geht, lesen Sie zuerst Was ist WhatsApp-OTP.
Die Grundlagen
- Basis-URL:
https://wapflow.net/api/otp/v1 - Authentifizierung: ein Header
Authorization: Bearer <key>bei jeder Anfrage. Live-Schlüssel beginnen mitwfo_live_, Test-Schlüssel mitwfo_test_. - Antwortformat:
{ "success": true, ... }bei Erfolg,{ "success": false, "error": { "code": "...", "message": "..." } }bei Fehlern. - Telefonnummer: mit Ländervorwahl, zum Beispiel
905321234567. Die API reduziert die Nummer auf Ziffern (+, Leerzeichen und Bindestriche werden entfernt) und erwartet 10 bis 15 Ziffern. Elfstellige Nummern, die mit 0 beginnen, werden als türkische Nummern behandelt und erhalten vorne 90.
Den API-Schlüssel erstellen Sie auf der Seite WapFlow OTP im WapFlow-Panel. Ein Schlüssel wird nur einmal bei der Erstellung angezeigt; bewahren Sie ihn in einer Umgebungsvariable auf Ihrem Server auf.
Vier Endpunkte
| Endpunkt | Zweck |
|---|---|
| POST /send | Erzeugt den Code und sendet ihn per WhatsApp. phone ist Pflicht; optional sind code_length (4-8), ttl (60-900 s), lang und app_name. |
| POST /verify | Prüft den vom Nutzer eingegebenen Code. phone und code sind Pflicht; wenn Sie request_id übergeben, wird genau diese Anfrage geprüft. |
| GET /status/:request_id | Liefert den Status der Anfrage: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Zeigt, ob der Schlüssel gültig ist, den Tarif, die Zahl der verbundenen Konten und den Kontingentverbrauch des Monats. |
Nach 5 Fehlversuchen wird eine Anfrage gesperrt, und ein bestätigter Code lässt sich nicht erneut verwenden. Lassen Sie request_id weg, wird der zuletzt gesendete, noch gültige Code an diese Nummer mit diesem Schlüssel geprüft. Da mehrere Sitzungen gleichzeitig bestehen können, empfehlen wir, die request_id zu speichern und beim Prüfen zurückzugeben.
Ein erster Versuch mit cURL
# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"phone":"905321234567","app_name":"Acme"}'
# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'
Machen Sie den ersten Versuch mit einem wfo_test_-Schlüssel: Es wird keine WhatsApp-Nachricht gesendet, kein Kontingent verbraucht, und der Code kommt im Feld test_code der Antwort zurück.
PHP-Beispiel
<?php
function wapflow_otp(string $path, array $body): array {
$ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$res = json_decode(curl_exec($ch), true) ?: [];
curl_close($ch);
return $res;
}
$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }
Node.js-Beispiel
Das Beispiel nutzt das eingebaute fetch (Node.js 18 oder neuer) und muss als ES-Modul laufen.
const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
const res = await fetch(BASE + path, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }
Python-Beispiel
import os
import requests
BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}
def otp(path, body):
return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()
sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
pass # signed in
Fehlerbehandlung
Behandeln Sie Senden und Prüfen getrennt. Liefert ein Versand success: false, reagieren Sie auf den Fehlercode:
| HTTP / Code | Was zu tun ist |
|---|---|
| 401 invalid_key | Prüfen Sie den Schlüssel; er wurde möglicherweise widerrufen oder falsch eingegeben. |
| 402 no_subscription, subscription_expired | Starten oder verlängern Sie das Abo. |
| 422 invalid_phone | Bitten Sie den Nutzer, die Nummer mit Ländervorwahl erneut einzugeben. |
| 429 rate_limited | Versuchen Sie es nach den Sekunden aus retry_after der Antwort erneut. |
| 429 quota_exceeded | Das monatliche Kontingent ist aufgebraucht; erhöhen Sie den Tarif oder warten Sie auf den nächsten Zeitraum. |
| 429 daily_limit_reached | Die verbundenen Konten haben ihr Tageslimit erreicht; versuchen Sie es nach retry_after erneut (ab 00:00 Uhr am nächsten Tag, türkische Zeit). Dafür wird kein Kontingent verbraucht. |
| 503 no_account_connected, send_failed | Stellen Sie sicher, dass ein verbundenes, aktiviertes WhatsApp-Konto vorhanden ist; versuchen Sie es kurz darauf erneut. |
Bei der Prüfung kann eine HTTP-200-Antwort trotzdem valid als false enthalten. Das Feld reason nennt den Grund: invalid_code, expired, too_many_attempts, already_verified oder not_found. Bei einem falschen Code zeigt attempts_left zeigt, wie viele Versuche übrig sind; wenn Sie das an den Nutzer weitergeben, wird die Nutzung angenehmer.
Limits und Nutzererlebnis
- Eine Nummer kann 1 Code pro 60 Sekunden, 5 pro Stunde und 10 pro Tag erhalten. Setzen Sie einen 60-Sekunden-Countdown auf Ihre Schaltfläche „Erneut senden“.
- Es gibt 60 Versände pro Minute je API-Schlüssel, 120 Anfragen pro Minute je IP-Adresse und für die Prüfung 10 Versuche pro Minute je Nummer.
- Das Tageslimit und das Aufwärmen neuer Nummern beeinflussen den Versand; Details finden Sie in unserem Beitrag zur Verringerung des Sperrrisikos.
Sicherheits-Checkliste
- Verwenden Sie den API-Schlüssel nie im Browser, in einer mobilen App oder in öffentlichem Code; führen Sie die Aufrufe von Ihrem Server aus.
- Prüfen Sie den Code immer serverseitig mit
/verify; vertrauen Sie keiner „bestätigt“-Markierung aus dem Browser. - Bewahren Sie den Schlüssel in einer Umgebungsvariable auf und nicht im Repository.
- Setzen Sie vor dem Versand eigene Limits und bei Bedarf ein CAPTCHA ein; Missbrauch kann Ihr Kontingent aufzehren.
- Halten Sie für kritische Vorgänge einen Ersatzkanal bereit (SMS oder E-Mail). WapFlow OTP ist nicht die offizielle WhatsApp Business API und garantiert keine Zustellung.
Wenn Sie WordPress oder WooCommerce nutzen, können Sie auf Programmierung verzichten und das Plugin verwenden. Die Tarife finden Sie auf der Preisseite, einen Produktüberblick auf der WapFlow-OTP-Seite.
Häufig gestellte Fragen
Was ändert sich beim Livegang?
Nur der Schlüssel. Ein Test-Schlüssel beginnt mit wfo_test_; seine Versand- und Limitregeln entsprechen denen eines Live-Schlüssels, ein aktives Abo ist trotzdem erforderlich.
Muss ich request_id mitsenden?
Nein, es wird aber empfohlen. Lassen Sie sie weg, wird der zuletzt gesendete, noch gültige Code an diese Nummer geprüft.
Kann ich den Nachrichtentext ändern?
Ja. Im Panel legen Sie Anwendungsnamen, Nachrichtenvorlage, Codelänge, Gültigkeit und Sprache fest. Die Vorlage verwendet die Variablen {code}, {app} und {minutes}. Pro Anfrage können Sie diese mit app_name, code_length, ttl und lang überschreiben.
Wie erfahre ich, dass die Nachricht zugestellt wurde?
Fragen Sie die Anfrage mit /status/:request_id ab; Sie können die Status sent, delivered und read sehen. Die Zustellinformationen hängen von WhatsApp ab und sind nicht garantiert.
Ist diese API auch in der Windows-App verfügbar?
Nein. WapFlow OTP ist ein eigenständiger Cloud-Dienst.


