· 6 min · TextMeFlow Team

Tester l'API WhatsApp avec cURL et Postman avant la mise en prod

La plupart des bugs d'intégration apparaissent une fois le code déjà branché sur un gestionnaire de formulaire, un webhook de CRM ou une tâche cron, ce qui les rend pénibles à isoler. La solution : tester d'abord l'API seule, avec rien d'autre qu'un terminal, avant que ce code n'existe. Quinze minutes avec cURL (ou Postman, si vous préférez une interface graphique) permettent de repérer les trois causes de presque tous les tickets « ça ne marche pas » : un numéro au mauvais format, une session WhatsApp qui n'est pas réellement appairée, et une mauvaise lecture de ce que signifient vraiment une réponse 202 et une réponse 429.

Voici cette séquence pas à pas, avec l'API TextMeFlow.

Récupérez votre clé API et vérifiez votre compte

Chaque compte reçoit à l'inscription une clé API de la forme tmf_<your_api_key>. Avant d'envoyer quoi que ce soit, vérifiez que la clé fonctionne et consultez votre plan et votre consommation actuels :

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

Un 200 avec le JSON de votre compte signifie que la clé est valide. Un 401 signifie que vous l'avez mal copiée ou qu'elle appartient à un autre environnement : vérifiez-le avant de déboguer quoi que ce soit en aval. Si vous utilisez Postman, définissez {{api_key}} comme variable de collection et réutilisez-la dans l'en-tête Authorization de chaque requête, plutôt que de coller la clé dans chacune.

Vérifiez que WhatsApp est bien appairé

Une clé API valide ne signifie pas que WhatsApp est connecté. TextMeFlow se relie à un vrai compte WhatsApp via un appairage par QR code, et les messages envoyés avant l'appairage (ou après la perte d'une session) échouent même si la requête est parfaitement formée. Vérifiez l'état de l'appairage avant de tester l'envoi :

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

Si le statut n'est pas « connected », appairez d'abord (POST /v1/accounts/me/pair renvoie un QR code à scanner), puis interrogez /v1/accounts/me/pair/{pair_id}/status jusqu'à ce que le statut passe à connected. Sauter cette étape est la raison la plus fréquente pour laquelle une intégration « qui fonctionnait » n'envoie soudain plus rien, généralement parce que le téléphone appairé est passé hors ligne ou que quelqu'un a déconnecté la session WhatsApp ailleurs.

Envoyez un vrai message de test

Avec une clé valide et une session active, envoyez d'abord un message à votre propre numéro, pas à celui d'un client :

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": "Message de test depuis l’API — à ignorer"
  }'

Un appel réussi renvoie 202 Accepted avec un message_id et status: "queued", et non "sent". La distinction est importante : un 202 signifie que l'API a accepté la tâche dans la file d'envoi, pas que WhatsApp a déjà remis le message. Conservez le message_id et consultez-le quelques secondes plus tard :

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

Pour tester un média, ajoutez un champ media_url pointant vers une image ou un PDF public : les pièces jointes jusqu'à 100 Mo fonctionnent de la même façon, sans endpoint distinct.

Déclenchez volontairement les erreurs que vous rencontrerez en production

Ne tester que le cas idéal prouve seulement que l'API fonctionne quand tout est parfait, ce qui n'est pas l'environnement dans lequel tourne votre code de production. Provoquez donc les cas d'échec pour que votre gestion d'erreurs soit réellement éprouvée :

  • Mauvais format de numéro : envoyez "to": "0472000000" au lieu du format E.164 (+32...). Vous devriez obtenir une erreur 4xx avec un message clair, pas un envoi abandonné en silence. Si votre formulaire collecte des numéros sans indicatif pays, c'est le bug que vous rencontrerez le plus souvent en conditions réelles : consultez le guide de validation des numéros de téléphone pour la correction.
  • Limite de débit : lancez dix requêtes en moins d'une seconde avec une boucle shell rapide. TextMeFlow applique environ 1 message par seconde en régime soutenu ; au-delà, vous recevez 429 Too Many Requests. Vérifiez que votre intégration ralentit et réessaie plutôt que de boucler à toute vitesse : voir gérer les limites de débit et le statut des messages pour le schéma de nouvelle tentative.
  • Session expirée ou déconnectée : déconnectez-vous de WhatsApp Web sur l'appareil appairé (ou appelez DELETE /v1/accounts/me/session) et renvoyez un message. Vous voulez voir quelle erreur revient pour que votre code puisse vous alerter au lieu d'échouer en silence pendant des jours.

Tests à la sauce TextMeBot (hérité)

Si vous migrez depuis TextMeBot, l'endpoint de remplacement direct GET /send.php accepte la même chaîne de requête que votre ancien code utilise déjà :

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

Il renvoie du HTML brut avec Result: <b>Success</b> ou Result: <b>Failed</b> : tout code qui recherche cette chaîne continue donc de fonctionner sans modification pendant que vous préparez le passage à /v1/messages. Tous les détails figurent dans la checklist de migration depuis TextMeBot.

Construisez une collection Postman une fois, réutilisez-la toujours

Si votre équipe doit intervenir plus d'une fois sur cette intégration, transformer ces appels cURL en petite collection Postman est vite rentable : une requête par endpoint (accounts/me, pair, messages en POST, messages/{id} en GET), la clé API en variable de collection et un exemple de réponse enregistré pour chacune. Les nouveaux arrivants peuvent alors vérifier en moins d'une minute que l'intégration est vivante sans lire de code, ce qui est précieux quand un ticket de support demande « le truc WhatsApp est-il en panne ? » et qu'il faut répondre oui ou non rapidement.

La forme complète des requêtes et des réponses, avec chaque champ et chaque code d'erreur, est documentée dans la référence de l'API.

Une fois que vos appels de test se comportent comme prévu (202 à l'envoi, un vrai message_id, des erreurs claires sur une entrée invalide), brancher ces mêmes appels dans votre application est la partie facile. Inscrivez-vous au plan gratuit et parcourez cette checklist avec votre propre compte avant d'écrire la moindre ligne de code d'intégration.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours