· 5 min · TextMeFlow Team

WhatsApp-Nachricht senden mit .NET/C# und der API

Die meisten Anleitungen zur WhatsApp API gehen von PHP oder Node aus. Wenn dein Stack .NET ist, ist die Integration genauso einfach, es ist schlicht JSON über HTTPS. Ein paar C#-spezifische Details (typisierter HttpClient, asynchrone Prüfung der Webhook-Signatur, Retry-Behandlung) solltest du aber von Anfang an richtig machen. Diese Anleitung zeigt, wie du in einer ASP.NET-Core-App eine Nachricht sendest, ihren Status abfragst und eingehende Antworten verifizierst.

Eine Nachricht mit HttpClient senden

Registriere einen benannten HttpClient für TextMeFlow in deinem DI-Container, damit Basisadresse und Auth-Header einmal gesetzt werden und nicht bei jedem Aufruf:

// Program.cs
builder.Services.AddHttpClient("textmeflow", client =>
{
    client.BaseAddress = new Uri("https://api.textmeflow.eu");
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", builder.Configuration["TextMeFlow:ApiKey"]);
});

Lege den API-Key in der Konfiguration ab (appsettings.json mit User Secrets lokal, in Produktion eine Umgebungsvariable oder ein Key Vault) und schreib ihn niemals fest in den Code.

Eine Nachricht zu senden ist ein einziger POST auf /v1/messages:

public record SendMessageRequest(string To, string Text, string? MediaUrl = null, bool Urgent = false);
public record SendMessageResponse(string MessageId, string Status);

public class TextMeFlowClient
{
    private readonly HttpClient _http;

    public TextMeFlowClient(IHttpClientFactory factory) => _http = factory.CreateClient("textmeflow");

    public async Task<SendMessageResponse?> SendAsync(SendMessageRequest request, CancellationToken ct = default)
    {
        var response = await _http.PostAsJsonAsync("/v1/messages", request, ct);

        if (response.StatusCode == HttpStatusCode.TooManyRequests)
        {
            // Rate Limit oder Monatskontingent erreicht, siehe unten
            throw new TextMeFlowRateLimitException();
        }

        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<SendMessageResponse>(cancellationToken: ct);
    }
}

to muss E.164 sein (+32472932208, mit führendem +). Eine Nummer ohne Ländervorwahl ist der häufigste Integrationsfehler überhaupt, unabhängig von der Sprache. Ein erfolgreicher Aufruf liefert 202 Accepted mit einer message_id und status: queued zurück, keinen endgültigen Zustellstatus: Die WhatsApp-Zustellung läuft asynchron. Wenn dein Workflow wissen muss, wann eine Nachricht tatsächlich ankommt, frage GET /v1/messages/{id} ab oder, besser noch, lausche auf den Delivery-Webhook, statt in einer Schleife zu pollen.

429-Fehler behandeln, ohne die Nachricht zu verlieren

Ein 429 bedeutet, dass entweder das Limit pro Nummer (1 Nachricht/Sek., 60/Min., 1.000/Stunde) oder das Monatskontingent des Tarifs erreicht wurde. Beide Fälle brauchen eine andere Behandlung: Ein Rate Limit ist vorübergehend und lohnt einen erneuten Versuch mit Backoff, ein erschöpftes Kontingent scheitert dagegen weiter, bis die Abrechnungsperiode zurückgesetzt wird oder du upgradest. Wiederholungen in enger Schleife kosten dann nur Zeit. Eine einfache Polly-Retry-Policy deckt den Rate-Limit-Fall sauber ab:

var retryPolicy = Policy
    .Handle<TextMeFlowRateLimitException>()
    .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)));

Drei Versuche mit exponentiellem Backoff reichen, um eine kurze Lastspitze abzufangen, ohne eine Schleife doppelter Sendungen zu riskieren. Wenn du viele Nachrichten in die Warteschlange stellst (Erinnerungen, Bestellupdates), schick sie über eine Hintergrund-Queue, IHostedService mit Channel<T> oder Hangfire/Quartz.NET, falls du ohnehin eines betreibst, statt sie alle aus einem einzigen Request-Handler abzufeuern.

Eingehende Webhooks verifizieren

Kundenantworten kommen als POST an den Endpoint, den du unter /admin/webhook konfigurierst, signiert mit HMAC-SHA256 über den rohen Request-Body in einem X-TextMeFlow-Signature: sha256=<hex>-Header. In ASP.NET Core wird der Body-Stream vom Model Binding verbraucht, bevor eine typische Action-Methode läuft. Lies ihn daher manuell in einer Minimal API oder einer eigenen Middleware aus, bevor irgendetwas deserialisiert:

app.MapPost("/webhooks/textmeflow", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body);
    var raw = await reader.ReadToEndAsync();

    var secret = Encoding.UTF8.GetBytes(builder.Configuration["TextMeFlow:WebhookSecret"]!);
    var computed = "sha256=" + Convert.ToHexString(
        new HMACSHA256(secret).ComputeHash(Encoding.UTF8.GetBytes(raw))).ToLowerInvariant();

    var received = request.Headers["X-TextMeFlow-Signature"].ToString();
    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(computed), Encoding.UTF8.GetBytes(received)))
    {
        return Results.Unauthorized();
    }

    var payload = JsonSerializer.Deserialize<WebhookPayload>(raw);
    // Payload speichern, über X-TextMeFlow-Event-Id deduplizieren, schnell mit 200 antworten, danach verarbeiten
    return Results.Ok();
});

CryptographicOperations.FixedTimeEquals ist der Constant-Time-Vergleich von .NET. Nutze ihn statt == oder SequenceEqual, die beide beim ersten abweichenden Byte abbrechen und so Timing-Informationen preisgeben. Antworte innerhalb von 10 Sekunden, sonst wertet TextMeFlow das als fehlgeschlagene Zustellung und versucht es bis zu 5 Mal erneut. Speichere das Event und erledige langsame Arbeit (CRM-Update, Bestellabfrage) nach der Rückgabe von 200, nicht davor. Die vollständige Referenz zu Headern und Retries steht in der Webhook-Dokumentation, und die Signatur-Mechanik wird ausführlicher in WhatsApp-Webhook-Signaturen prüfen behandelt, falls du die PHP-, Python- und Node-Entsprechungen nebeneinander sehen willst.

Ein minimales End-to-End-Beispiel

Zusammengesetzt braucht eine Konsolen-App, die eine Bestätigung sendet und Antworten protokolliert, drei Dinge: eine HttpClient-Registrierung, den SendAsync-Aufruf von oben und eine kleine ASP.NET-Core-App (oder Azure Function), die den Webhook-Endpoint bereitstellt. Es gibt kein SDK zu installieren: System.Net.Http.Json und System.Security.Cryptography aus der Basisklassenbibliothek decken alles ab.

Probier es aus

Der kostenlose Tarif enthält 50 Nachrichten pro Monat, für immer. Genug, um diesen Ablauf Ende zu Ende aufzubauen und eine echte Antwort über deinen Webhook eintreffen zu sehen, bevor du dich festlegst. Erstelle ein kostenloses Konto und sende deine erste Nachricht aus C# in wenigen Minuten.

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