Envoyer du WhatsApp depuis Django avec l'API TextMeFlow
Les projets Django parlent déjà aux API tierces via requests, donc envoyer des messages WhatsApp ne demande aucun SDK supplémentaire — juste une petite classe client, une tâche Celery qui respecte le backoff du rate limit, et une vue webhook qui vérifie la signature avant de toucher le corps de la requête. Cet article couvre les trois, pensé pour s'intégrer dans un projet Django existant plutôt que dans un script isolé.
Avant de commencer
- Créez un compte TextMeFlow gratuit — 50 messages par mois, à vie, sans carte bancaire et sans vérification Meta Business.
- Scannez le QR code du portail avec le téléphone qui détient le numéro WhatsApp à utiliser pour l'envoi.
- Copiez votre clé API depuis le tableau de bord et votre secret webhook depuis
/admin/webhook.
La référence complète des endpoints se trouve sur /docs/api ; tout ce qui suit cible POST /v1/messages sur https://api.textmeflow.eu.
Un client dans sa propre app
Gardez les détails HTTP hors des vues et des modèles — une app whatsapp avec une seule classe client suffit :
# whatsapp/client.py
import requests
from django.conf import settings
BASE_URL = "https://api.textmeflow.eu"
class TextMeFlowError(Exception):
pass
class RateLimited(TextMeFlowError):
def __init__(self, reason, retry_after_seconds):
self.reason = reason
self.retry_after_seconds = retry_after_seconds
super().__init__(f"rate limited: {reason}")
def send_message(to, text=None, media_url=None):
payload = {"to": to, "text": text, "media_url": media_url}
payload = {k: v for k, v in payload.items() if v is not None}
response = requests.post(
f"{BASE_URL}/v1/messages",
json=payload,
headers={"Authorization": f"Bearer {settings.TEXTMEFLOW_API_KEY}"},
timeout=10,
)
if response.status_code == 202:
return response.json()
if response.status_code == 429:
body = response.json()
raise RateLimited(body.get("reason"), body.get("retry_after_seconds"))
raise TextMeFlowError(f"unexpected status {response.status_code}: {response.text}")
Gardez to au format E.164 (+32472932208) — un numéro sans le + et l'indicatif pays initiaux est rejeté avec un 422, et c'est l'erreur d'intégration la plus fréquente, dans n'importe quel langage. media_url est optionnel et accepte n'importe quel fichier accessible publiquement jusqu'à 100 Mo ; omettez-le pour un message texte simple. Un 202 signifie que le message est en file d'attente, pas qu'il est livré — le message_id de la réponse sert ensuite à vérifier le vrai statut, pas le simple succès de l'appel HTTP.
Ajoutez la clé depuis l'environnement, jamais en dur :
# settings.py
TEXTMEFLOW_API_KEY = os.environ["TEXTMEFLOW_API_KEY"]
TEXTMEFLOW_WEBHOOK_SECRET = os.environ["TEXTMEFLOW_WEBHOOK_SECRET"]
Relancer sur 429 avec Celery
Comme la plupart des projets Django font déjà tourner Celery pour tout ce qui touche une API externe, laissez la politique de relance de la tâche gérer l'attente plutôt qu'un time.sleep bloquant dans un cycle requête-réponse :
# whatsapp/tasks.py
from celery import shared_task
from .client import send_message, RateLimited, TextMeFlowError
@shared_task(bind=True, max_retries=5)
def send_whatsapp_message(self, to, text):
try:
send_message(to=to, text=text)
except RateLimited as exc:
raise self.retry(exc=exc, countdown=exc.retry_after_seconds or 2 ** self.request.retries * 5)
except TextMeFlowError:
raise
Un corps 429 contient toujours reason (burst_exceeded ou hourly_exceeded) et retry_after_seconds, documenté sur la page des limites de débit — countdown lit directement cette valeur au lieu de deviner un intervalle de backoff. Pour la question plus large de savoir s'il faut interroger GET /v1/messages/{id} ou faire confiance aux webhooks pour le statut de livraison, voir gérer les limites de débit et le statut des messages.
Vérifier les webhooks entrants dans une vue
Les réponses des clients sont envoyées en POST vers l'endpoint configuré dans /admin/webhook, signées en HMAC-SHA256 sur le corps de requête brut dans un en-tête X-TextMeFlow-Signature: sha256=<hex>. Le middleware CSRF de Django et request.POST s'attendent tous deux à des données de formulaire, donc il faut une vue simple @csrf_exempt qui lit request.body avant tout parsing :
# whatsapp/views.py
import hmac
import hashlib
import json
from django.conf import settings
from django.http import HttpResponse, HttpResponseForbidden
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from .models import ProcessedWebhookEvent
from .tasks import handle_incoming_message
@csrf_exempt
@require_POST
def textmeflow_webhook(request):
raw = request.body
expected = "sha256=" + hmac.new(
settings.TEXTMEFLOW_WEBHOOK_SECRET.encode(), raw, hashlib.sha256
).hexdigest()
received = request.headers.get("X-TextMeFlow-Signature", "")
if not hmac.compare_digest(expected, received):
return HttpResponseForbidden()
event_id = request.headers.get("X-TextMeFlow-Event-Id")
if ProcessedWebhookEvent.objects.filter(event_id=event_id).exists():
return HttpResponse(status=200)
ProcessedWebhookEvent.objects.create(event_id=event_id)
handle_incoming_message.delay(json.loads(raw))
return HttpResponse(status=200)
hmac.compare_digest s'exécute en temps constant — utilisez-le plutôt que ==, qui s'arrête au premier octet différent et fuit ainsi une information de timing. X-TextMeFlow-Event-Id reste stable à travers les relances, donc une contrainte unique sur cette colonne dans ProcessedWebhookEvent suffit à éviter de traiter deux fois le même message entrant : TextMeFlow relance les webhooks non livrés jusqu'à 5 fois avec un backoff croissant, et tout ce qui n'est pas un 2xx en moins de 10 secondes compte comme un échec. Renvoyer 200 immédiatement et confier le vrai travail à une tâche Celery via .delay() compte ici — une vue lente ressemble, du point de vue de TextMeFlow, à un timeout et déclenche une relance inutile. La liste complète des en-têtes et le format du payload sont dans la documentation webhooks ; la mécanique de signature est traitée plus en détail, avec PHP/Python/Node côte à côte, dans vérifier les signatures des webhooks WhatsApp.
Branchez l'URL comme d'habitude :
# urls.py
from whatsapp.views import textmeflow_webhook
urlpatterns = [
path("webhooks/textmeflow/", textmeflow_webhook, name="textmeflow-webhook"),
# ...
]
En résumé
Une intégration Django demande trois éléments : un client basé sur requests qui lit la clé API depuis les settings, une tâche Celery dont le countdown de relance respecte retry_after_seconds au lieu d'une attente fixe, et une vue exemptée de CSRF qui vérifie la signature HMAC avec hmac.compare_digest avant de faire quoi que ce soit avec le payload — aucune dépendance supplémentaire au-delà de ce qu'une stack Django typique possède déjà. Démarrez gratuitement et vous aurez une tâche d'envoi et une vue webhook opérationnelles avant votre prochain déploiement.
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