· 5 min · TextMeFlow Team

WhatsApp senden aus Django mit der TextMeFlow API

Django-Projekte sprechen bereits über requests mit externen APIs, daher braucht der Versand von WhatsApp-Nachrichten kein zusätzliches SDK — nur eine kleine Client-Klasse, einen Celery-Task, der den Rate-Limit-Backoff respektiert, und eine Webhook-View, die Signaturen prüft, bevor sie den Request-Body anfasst. Dieser Artikel behandelt alle drei Teile, geschrieben für ein bestehendes Django-Projekt statt für ein isoliertes Skript.

Bevor du startest

  1. Erstelle ein kostenloses TextMeFlow-Konto — 50 Nachrichten pro Monat, dauerhaft, ohne Kreditkarte und ohne Meta-Business-Verifizierung.
  2. Scanne den QR-Code aus dem Portal mit dem Telefon, das die WhatsApp-Nummer hält, von der du versenden willst.
  3. Kopiere deinen API-Schlüssel aus dem Dashboard und dein Webhook-Secret aus /admin/webhook.

Die vollständige Endpoint-Referenz findest du unter /docs/api; alles Folgende zielt auf POST /v1/messages unter https://api.textmeflow.eu.

Ein Client in seiner eigenen App

Halte die HTTP-Details aus Views und Models heraus — eine whatsapp-App mit einer einzigen Client-Klasse reicht:

# 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}")

Halte to im E.164-Format (+32472932208) — eine Nummer ohne führendes + und Landesvorwahl wird mit einem 422 abgelehnt und ist in jeder Sprache der häufigste Integrationsfehler. media_url ist optional und akzeptiert jede öffentlich erreichbare Datei bis 100 MB; lass es für eine reine Textnachricht weg. Ein 202 bedeutet, dass die Nachricht in der Warteschlange steht, nicht dass sie zugestellt wurde — die message_id aus der Antwort nutzt du danach, um den tatsächlichen Status abzufragen, nicht die bloße Tatsache, dass der HTTP-Call erfolgreich war.

Füge den Schlüssel über die Umgebung hinzu, nicht hartkodiert:

# settings.py
TEXTMEFLOW_API_KEY = os.environ["TEXTMEFLOW_API_KEY"]
TEXTMEFLOW_WEBHOOK_SECRET = os.environ["TEXTMEFLOW_WEBHOOK_SECRET"]

Bei 429 mit Celery erneut versuchen

Da die meisten Django-Projekte für alles, was eine externe API anspricht, bereits Celery laufen lassen, überlässt du die Wartezeit der eigenen Retry-Policy des Tasks statt einem blockierenden time.sleep im Request-Response-Zyklus:

# 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

Ein 429-Body enthält immer reason (burst_exceeded oder hourly_exceeded) und retry_after_seconds, dokumentiert auf der Rate-Limits-Seite — countdown liest diesen Wert direkt aus, statt ein Backoff-Intervall zu raten. Zur größeren Frage, ob man GET /v1/messages/{id} pollen oder den Webhooks für den Zustellstatus vertrauen sollte, siehe Rate Limits und Message Status handhaben.

Eingehende Webhooks in einer View prüfen

Antworten von Kunden werden per POST an den Endpunkt gesendet, den du unter /admin/webhook konfigurierst, signiert mit HMAC-SHA256 über den rohen Request-Body in einem X-TextMeFlow-Signature: sha256=<hex>-Header. Djangos CSRF-Middleware und request.POST erwarten beide Formulardaten, daher muss das eine schlichte @csrf_exempt-View sein, die request.body liest, bevor irgendetwas geparst wird:

# 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 läuft in konstanter Zeit — benutze es statt ==, das beim ersten abweichenden Byte abbricht und dadurch Timing-Informationen verrät. X-TextMeFlow-Event-Id bleibt über Wiederholungen hinweg stabil, daher reicht ein eindeutiger Constraint auf dieser Spalte in ProcessedWebhookEvent, um zu verhindern, dass du dieselbe eingehende Nachricht zweimal verarbeitest: TextMeFlow wiederholt nicht zugestellte Webhooks bis zu 5-mal mit steigendem Backoff, und alles außer einem 2xx innerhalb von 10 Sekunden zählt als fehlgeschlagener Versuch. Sofort 200 zurückzugeben und die eigentliche Arbeit über .delay() an einen Celery-Task weiterzugeben ist hier entscheidend — eine langsame View sieht aus Sicht von TextMeFlow wie ein Timeout aus und wird unnötig erneut versucht. Die vollständige Header-Liste und das Payload-Format stehen in den Webhook-Docs; die Signatur-Mechanik wird ausführlicher behandelt, mit PHP/Python/Node nebeneinander, in WhatsApp-Webhook-Signaturen verifizieren.

Verknüpfe die URL wie gewohnt:

# urls.py
from whatsapp.views import textmeflow_webhook

urlpatterns = [
    path("webhooks/textmeflow/", textmeflow_webhook, name="textmeflow-webhook"),
    # ...
]

Zusammengefasst

Eine Django-Integration braucht drei Teile: einen requests-basierten Client, der den API-Schlüssel aus den Settings liest, einen Celery-Task, dessen Retry-countdown retry_after_seconds respektiert statt einer festen Wartezeit, und eine CSRF-freie View, die die HMAC-Signatur mit hmac.compare_digest prüft, bevor sie irgendetwas mit dem Payload tut — keine zusätzliche Abhängigkeit über das hinaus, was ein typischer Django-Stack bereits mitbringt. Jetzt kostenlos starten und du hast einen Sende-Task und eine Webhook-View noch vor deinem nächsten Deploy laufen.

Selbst WhatsApp-Nachrichten per API senden?

Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.

Für immer gratis