· 5 min · TextMeFlow Team

Envoyer un message WhatsApp en .NET/C# avec l'API

La plupart des guides d'API WhatsApp partent du principe que vous utilisez PHP ou Node. Si votre stack est .NET, l'intégration est tout aussi simple, ce n'est que du JSON sur HTTPS, mais quelques détails propres à C# (HttpClient typé, vérification asynchrone des signatures de webhook, gestion des nouvelles tentatives) méritent d'être bien réglés dès le départ. Ce guide présente l'envoi d'un message, la lecture de son statut et la vérification des réponses entrantes depuis une application ASP.NET Core.

Envoyer un message avec HttpClient

Enregistrez un HttpClient nommé pour TextMeFlow dans votre conteneur d'injection de dépendances, afin que l'adresse de base et l'en-tête d'authentification soient définis une seule fois et non à chaque appel :

// 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"]);
});

Conservez la clé d'API dans la configuration (appsettings.json avec les user secrets en local, une variable d'environnement ou un coffre de clés en production) et ne l'écrivez jamais en dur dans le code.

Envoyer un message se fait avec un seul POST vers /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)
        {
            // limite de débit ou quota mensuel atteint, voir ci-dessous
            throw new TextMeFlowRateLimitException();
        }

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

to doit être au format E.164 (+32472932208, avec le + initial). Un numéro sans indicatif pays est le bug d'intégration le plus courant, quel que soit le langage. Un appel réussi renvoie 202 Accepted avec un message_id et status: queued, et non un état de livraison final : la livraison WhatsApp est asynchrone. Si votre flux doit savoir quand un message arrive réellement, interrogez GET /v1/messages/{id} ou, mieux encore, écoutez le webhook de livraison plutôt que de scruter en boucle.

Gérer les 429 sans perdre le message

Un 429 signifie que la limite par numéro (1 msg/s, 60/min, 1 000/heure) ou le quota mensuel du forfait a été atteint. Ces deux cas appellent un traitement différent : une limite de débit est temporaire et mérite une nouvelle tentative avec temporisation, alors qu'un quota épuisé continuera d'échouer jusqu'à la réinitialisation de la période de facturation ou jusqu'à une mise à niveau, si bien que réessayer en boucle serrée ne fait que perdre du temps. Une simple politique de nouvelle tentative Polly couvre proprement le cas de la limite de débit :

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

Trois tentatives avec temporisation exponentielle suffisent pour absorber un pic bref sans risquer une boucle d'envois en double. Si vous mettez beaucoup de messages en file (rappels, mises à jour de commande), faites-les passer par une file en arrière-plan, IHostedService avec Channel<T>, ou Hangfire/Quartz.NET si vous en utilisez déjà un, plutôt que de tous les lancer depuis un seul gestionnaire de requête.

Vérifier les webhooks entrants

Les réponses des clients arrivent sous forme de POST vers le endpoint configuré dans /admin/webhook, signées en HMAC-SHA256 sur le corps brut de la requête dans un en-tête X-TextMeFlow-Signature: sha256=<hex>. Dans ASP.NET Core, le flux du corps est consommé par le model binding avant l'exécution d'une méthode d'action classique. Lisez-le donc manuellement dans une minimal API ou un middleware dédié, avant que quoi que ce soit ne le désérialise :

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);
    // stocker le payload, dédoublonner sur X-TextMeFlow-Event-Id, répondre 200 vite, traiter ensuite
    return Results.Ok();
});

CryptographicOperations.FixedTimeEquals est la comparaison en temps constant de .NET. Utilisez-la à la place de == ou de SequenceEqual, qui s'arrêtent tous deux au premier octet différent et laissent fuiter des informations de timing. Répondez dans les 10 secondes, faute de quoi TextMeFlow considère la livraison comme échouée et réessaie jusqu'à 5 fois. Enregistrez l'événement et effectuez les traitements lents (mise à jour du CRM, recherche de commande) après avoir renvoyé 200, pas avant. La référence complète des en-têtes et des nouvelles tentatives se trouve dans la documentation des webhooks, et le mécanisme de signature est détaillé dans vérifier les signatures des webhooks WhatsApp si vous voulez voir côte à côte les équivalents PHP, Python et Node.

Un exemple minimal de bout en bout

En résumé, une application console qui envoie une confirmation et journalise les réponses a besoin de trois éléments : un enregistrement HttpClient, l'appel SendAsync ci-dessus et une petite application ASP.NET Core (ou une Azure Function) exposant le endpoint webhook. Aucun SDK à installer : System.Net.Http.Json et System.Security.Cryptography de la bibliothèque de classes de base couvrent tout.

À essayer

Le forfait gratuit comprend 50 messages par mois, pour toujours. Suffisant pour monter ce flux de bout en bout et voir une vraie réponse arriver par votre webhook avant de vous engager. Créez un compte gratuit et envoyez votre premier message depuis C# en quelques minutes.

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