Intégration de l'API OTP WhatsApp : exemples PHP, Node.js et Python

Envoyer un code de vérification par WhatsApp se résume à deux appels à l'API WapFlow OTP : l'un envoie le code, l'autre vérifie ce que l'utilisateur a saisi. Dans ce guide, nous rassemblons le fonctionnement de l'API, des exemples cURL, PHP, Node.js et Python, la gestion des erreurs et les points de sécurité à surveiller. Les exemples suivent le format de la documentation officielle de l'API, avec seulement de légers ajouts pour la lisibilité. Si vous vous demandez ce qu'est le produit avant de commencer à coder, lisez d'abord Qu'est-ce que WhatsApp OTP.
Les bases
- URL de base :
https://wapflow.net/api/otp/v1 - Authentification : un en-tête
Authorization: Bearer <key>à chaque requête. Les clés de production commencent parwfo_live_, les clés de test parwfo_test_. - Format de réponse :
{ "success": true, ... }en cas de succès,{ "success": false, "error": { "code": "...", "message": "..." } }en cas d'échec. - Numéro de téléphone : avec l'indicatif pays, par exemple
905321234567. L'API ne conserve que les chiffres (les +, espaces et tirets sont supprimés) et attend entre 10 et 15 chiffres. Les numéros à onze chiffres commençant par 0 sont considérés comme turcs et reçoivent 90 devant.
Vous créez la clé API sur la page WapFlow OTP du panneau WapFlow. Une clé n'est affichée qu'une seule fois, au moment de sa création ; conservez-la dans une variable d'environnement sur votre serveur.
Quatre points de terminaison
| Point de terminaison | Rôle |
|---|---|
| POST /send | Génère le code et l'envoie par WhatsApp. phone est obligatoire ; code_length (4-8), ttl (60-900 s), lang et app_name sont facultatifs. |
| POST /verify | Contrôle le code saisi par l'utilisateur. phone et code sont obligatoires ; si vous transmettez request_id, cette demande précise est vérifiée. |
| GET /status/:request_id | Renvoie l'état de la demande : en file d'attente, envoyé, distribué, lu, échoué, vérifié ou expiré. |
| GET /me | Indique si la clé est valide, le forfait, le nombre de comptes connectés et la consommation du quota du mois. |
Après 5 mauvaises tentatives, une demande est verrouillée, et un code déjà vérifié ne peut plus être réutilisé. Si vous omettez request_id, c'est le dernier code non expiré envoyé à ce numéro avec cette clé qui est vérifié. Comme plusieurs sessions peuvent exister en parallèle, nous recommandons de stocker le request_id et de le renvoyer lors de la vérification.
Un premier essai avec 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"}'
Faites le premier essai avec une clé wfo_test_ : aucun message WhatsApp n'est envoyé, aucun quota n'est consommé, et le code est renvoyé dans le champ test_code de la réponse.
Exemple PHP
<?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 */ }
Exemple Node.js
L'exemple utilise le fetch intégré (Node.js 18 ou plus récent) et doit être exécuté comme un module ES.
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 */ }
Exemple Python
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
Gestion des erreurs
Traitez séparément l'envoi et la vérification. Si un envoi renvoie success: false, agissez selon le code d'erreur :
| HTTP / code | Que faire |
|---|---|
| 401 invalid_key | Vérifiez la clé ; elle a peut-être été révoquée ou mal saisie. |
| 402 no_subscription, subscription_expired | Souscrivez ou renouvelez l'abonnement. |
| 422 invalid_phone | Demandez à l'utilisateur de ressaisir le numéro avec l'indicatif pays. |
| 429 rate_limited | Réessayez après le nombre de secondes indiqué dans retry_after de la réponse. |
| 429 quota_exceeded | Le quota mensuel est épuisé ; passez à un forfait supérieur ou attendez la période suivante. |
| 429 daily_limit_reached | Les comptes connectés ont atteint leur limite quotidienne ; réessayez après retry_after (le lendemain à 00h00, heure de Turquie). Aucun quota n'est consommé. |
| 503 no_account_connected, send_failed | Assurez-vous qu'un compte WhatsApp connecté et activé existe ; réessayez peu après. |
Lors de la vérification, une réponse HTTP 200 peut quand même contenir valid à false. Le champ reason indique la cause : invalid_code, expired, too_many_attempts, already_verified ou not_found. En cas de mauvais code, attempts_left indique le nombre d'essais restants ; le transmettre à l'utilisateur améliore l'expérience.
Limites d'envoi et expérience utilisateur
- Un même numéro peut recevoir 1 code par 60 secondes, 5 par heure et 10 par jour. Affichez un compte à rebours de 60 secondes sur votre bouton « Renvoyer ».
- Il existe 60 envois par minute et par clé API, 120 requêtes par minute et par adresse IP et, pour la vérification, 10 tentatives par minute et par numéro.
- La limite quotidienne et la mise en chauffe des nouveaux numéros influent sur l'envoi ; pour les détails, consultez notre article sur la réduction du risque de blocage.
Liste de contrôle de sécurité
- N'utilisez jamais la clé API dans un navigateur, une application mobile ou un code public ; effectuez les appels depuis votre serveur.
- Vérifiez toujours le code sur le serveur avec
/verify; ne faites pas confiance à un indicateur « vérifié » venant du navigateur. - Conservez la clé dans une variable d'environnement, et en dehors de votre dépôt de code.
- Appliquez votre propre limitation de débit et, si besoin, un CAPTCHA avant d'envoyer un code ; les abus peuvent consommer votre quota.
- Gardez un canal de secours (SMS ou e-mail) pour les actions critiques. WapFlow OTP n'est pas l'API officielle WhatsApp Business et ne garantit pas la livraison.
Si vous utilisez WordPress ou WooCommerce, vous pouvez vous passer de développement et utiliser le plugin. Consultez la page tarifs pour les forfaits et la page WapFlow OTP pour la présentation du produit.
Questions fréquentes
Que change-t-il lors de la mise en production ?
Uniquement la clé. Une clé de test commence par wfo_test_, et ses règles d'envoi et de débit sont les mêmes qu'une clé de production ; un abonnement actif reste nécessaire.
Dois-je envoyer request_id ?
Non, mais c'est recommandé. Si vous l'omettez, c'est le dernier code non expiré envoyé à ce numéro qui est vérifié.
Puis-je modifier le texte du message ?
Oui. Dans le panneau, vous pouvez définir le nom de l'application, le modèle de message, la longueur du code, sa durée de validité et la langue. Le modèle utilise les variables {code}, {app} et {minutes}. Pour chaque requête, vous pouvez remplacer ces valeurs avec app_name, code_length, ttl et lang.
Comment savoir que le message a été distribué ?
Interrogez la demande avec /status/:request_id ; vous pouvez voir sent, delivered et read. Les informations de distribution dépendent de WhatsApp et ne sont pas garanties.
Cette API est-elle aussi disponible dans l'application Windows ?
Non. WapFlow OTP est un service cloud distinct.


