Limites de débit et statut des messages dans l'API TextMeFlow
La plupart des intégrations qui envoient des messages WhatsApp fonctionnent très bien en test, puis se mettent à perdre des messages en production dès que le volume augmente. La cause n'est généralement pas un appel d'API défectueux — c'est que personne n'a géré les réponses 429. TextMeFlow applique volontairement des limites de débit (voir le guide anti-spam pour comprendre pourquoi) : votre intégration doit donc s'y attendre, et non les traiter comme une erreur.
Ce guide couvre les deux choses que toute intégration de production devrait faire : temporiser correctement après un 429, et interroger le statut des messages au lieu de supposer qu'un 202 signifie « délivré ».
Pourquoi vous verrez des 429
Chaque plan dispose d'un plafond horaire et d'une limite de rafale par minute — consultez les chiffres actuels sur la page des limites de débit. Deux situations déclenchent un 429 sur POST /v1/messages :
- Rafale dépassée — trop d'envois dans la dernière minute.
reason: burst_exceeded. - Plafond horaire dépassé — vous avez atteint le plafond horaire du plan.
reason: hourly_exceeded.
Les deux réponses contiennent dans leur corps une sémantique Retry-After : vous savez donc exactement combien de temps attendre — pas de devinette, pas de pause fixe.
Réessayer avec un délai croissant, pas avec un délai fixe
Une boucle de nouvelle tentative naïve (sleep(5); retry) fait soit perdre du temps, soit marteler l'API au moment précis où elle vous demande de ralentir. Respectez l'indication de nouvelle tentative et ajoutez par-dessus un délai exponentiel comme marge de sécurité.
Node.js :
async function sendMessage(to, text, attempt = 1) {
const res = await fetch('https://api.textmeflow.eu/v1/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TEXTMEFLOW_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, text }),
});
if (res.status === 429 && attempt <= 5) {
const body = await res.json();
const wait = (body.retry_after_seconds ?? 30) * attempt;
await new Promise((r) => setTimeout(r, wait * 1000));
return sendMessage(to, text, attempt + 1);
}
return res.json();
}
Python :
import time
import requests
def send_message(to, text, attempt=1):
res = requests.post(
"https://api.textmeflow.eu/v1/messages",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"to": to, "text": text},
)
if res.status_code == 429 and attempt <= 5:
wait = res.json().get("retry_after_seconds", 30) * attempt
time.sleep(wait)
return send_message(to, text, attempt + 1)
return res.json()
Plafonnez le nombre de tentatives (cinq suffisent largement) et abandonnez ensuite de façon bruyante — laisser tomber un message en silence est pire que journaliser un échec que votre équipe peut traiter.
202 signifie « en file d'attente », pas « délivré »
POST /v1/messages renvoie 202 Accepted avec un message_id dès que le message est mis en file d'attente. C'est avant même l'envoi, et a fortiori avant la lecture — le moteur de cadence de TextMeFlow peut le retenir pour respecter les heures calmes ou le délai aléatoire décrit dans le guide anti-spam.
Si votre application a besoin de connaître le résultat réel — pour une confirmation de réservation, un reçu de paiement, tout ce qu'une personne attend — interrogez GET /v1/messages/{id} avec le message_id reçu :
async function waitForStatus(messageId, maxTries = 10) {
for (let i = 0; i < maxTries; i++) {
const res = await fetch(`https://api.textmeflow.eu/v1/messages/${messageId}`, {
headers: { Authorization: `Bearer ${process.env.TEXTMEFLOW_API_KEY}` },
});
const data = await res.json();
if (data.status === 'delivered' || data.status === 'failed') return data;
await new Promise((r) => setTimeout(r, 3000));
}
return null; // toujours en attente après maxTries — ne bloquez pas indéfiniment dessus
}
Pour tout ce qui est moins urgent, inutile d'interroger : configurez un webhook et laissez TextMeFlow vous envoyer les changements de statut. L'interrogation sert au contrôle ponctuel « ce message précis est-il arrivé » ; les webhooks servent à tout suivre à grande échelle.
Ne luttez pas contre le régulateur avec urgent
POST /v1/messages accepte un indicateur urgent: true qui contourne la mise en forme des heures calmes. Il existe pour le cas du code de porte à 23 h, pas pour sauter la file d'attente par commodité — chaque envoi forcé pendant les heures calmes augmente le score de risque de votre compte. Réservez-le aux messages qu'une personne attend activement à cet instant.
Mettre le tout ensemble
Un chemin d'envoi résilient ressemble à ceci : envoyer avec une nouvelle tentative sur 429, récupérer un message_id, soit l'interroger pour les flux urgents, soit laisser votre gestionnaire de webhook mettre à jour votre propre base de données de façon asynchrone, et réserver urgent aux messages réellement urgents. C'est toute la différence entre une intégration qui perd silencieusement des messages sous charge et une qui fonctionne tout simplement.
Commencez avec le plan gratuit — 50 messages/mois, sans carte bancaire — et intégrez la logique de nouvelle tentative avant d'en avoir besoin, pas après votre premier samedi chargé.
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