· 3 min · TextMeFlow Team

Envoyer un message WhatsApp en Java (Spring Boot)

Spring Boot contient déjà tout ce qu'il faut pour dialoguer avec l'API TextMeFlow — pas de SDK tiers, pas de génération de code. RestClient (intégré depuis Spring Framework 6.1) envoie les messages, une petite boucle de nouvelles tentatives gère les limites de débit, et javax.crypto.Mac vérifie les webhooks entrants. Ce guide passe en revue les trois, avec du code que vous pouvez intégrer tel quel dans une classe de service.

Avant de commencer

  1. Créez un compte TextMeFlow gratuit — 50 messages par mois, pour toujours, sans carte bancaire et sans vérification Meta Business.
  2. Scannez le code QR depuis le portail avec le téléphone qui contient le numéro WhatsApp depuis lequel vous voulez envoyer.
  3. Copiez votre clé API depuis le tableau de bord.

La référence complète des endpoints se trouve sur /fr/docs/api ; tout ce qui suit cible POST /v1/messages.

Envoyer un message

Un client minimal se résume à un bean RestClient, un record pour le corps de la requête et un jeton bearer :

public record SendRequest(String to, String text, String mediaUrl) {}
public record SendResponse(String messageId, String status) {}

@Service
public class TextMeFlowClient {

    private final RestClient restClient;

    public TextMeFlowClient(@Value("${textmeflow.api-key}") String apiKey) {
        this.restClient = RestClient.builder()
            .baseUrl("https://api.textmeflow.eu/v1")
            .defaultHeader("Authorization", "Bearer " + apiKey)
            .build();
    }

    public SendResponse send(SendRequest message) {
        return restClient.post()
            .uri("/messages")
            .contentType(MediaType.APPLICATION_JSON)
            .body(message)
            .retrieve()
            .body(SendResponse.class);
    }
}

Conservez le champ to au format E.164 (+ suivi de l'indicatif du pays) — tout autre format est rejeté avec une erreur 422. mediaUrl est facultatif et accepte tout fichier accessible publiquement jusqu'à 100 Mo (image, PDF, message vocal) ; laissez-le null pour un simple message texte. Une réponse 202 signifie que le message est mis en file d'attente, pas encore qu'il est délivré — le messageId renvoyé vous servira à vérifier le statut réel plus tard.

Réessayer après un 429 sans marteler l'API

TextMeFlow applique volontairement des limites de débit — un plafond de rafale par minute et un plafond horaire selon le plan, détaillés sur la page des limites de débit. Le corps d'une réponse 429 contient reason (burst_exceeded ou hourly_exceeded) et retryAfterSeconds : inutile donc de deviner le délai d'attente :

public record RateLimitBody(String reason, int retryAfterSeconds) {}

public SendResponse sendWithRetry(SendRequest message, int maxAttempts) throws InterruptedException {
    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
            return restClient.post()
                .uri("/messages")
                .contentType(MediaType.APPLICATION_JSON)
                .body(message)
                .retrieve()
                .body(SendResponse.class);
        } catch (HttpClientErrorException.TooManyRequests ex) {
            RateLimitBody rl = ex.getResponseBodyAs(RateLimitBody.class);
            long waitMs = rl.retryAfterSeconds() * 1000L * attempt;
            Thread.sleep(waitMs);
        }
    }
    throw new IllegalStateException("gave up after " + maxAttempts + " attempts");
}

Cinq tentatives suffisent largement en pratique. Multiplier le délai suggéré par le numéro de la tentative ajoute une marge de sécurité à ce que l'API vous a déjà indiqué, sans retomber sur un Thread.sleep(5000) fixe qui fait soit perdre du temps, soit réessayer trop tôt. Pour le raisonnement complet sur l'interrogation de GET /v1/messages/{id} par rapport à la confiance accordée aux webhooks pour le statut de livraison, consultez le guide sur les limites de débit et le statut des messages.

Recevoir les réponses : un gestionnaire de webhook signé

Chaque réponse WhatsApp entrante est envoyée en POST à l'endpoint que vous configurez dans /admin/webhook, signée avec X-TextMeFlow-Signature: sha256=<hex> — un HMAC-SHA256 du corps brut de la requête, calculé avec le secret affiché une seule fois à la création. Lier les octets bruts (et non un DTO déjà parsé) est ce qui rend la vérification de signature valide :

@RestController
public class WebhookController {

    @Value("${textmeflow.webhook-secret}")
    private String secret;

    @PostMapping("/webhooks/textmeflow")
    public ResponseEntity<Void> handle(@RequestBody byte[] rawBody,
                                        @RequestHeader("X-TextMeFlow-Signature") String signature,
                                        @RequestHeader("X-TextMeFlow-Event-Id") String eventId) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal(rawBody));

        if (!MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), signature.getBytes(StandardCharsets.UTF_8))) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        // INSERT ... ON CONFLICT (event_id) DO NOTHING, puis transmission à un traitement asynchrone.
        return ResponseEntity.ok().build();
    }
}

MessageDigest.isEqual s'exécute en temps constant : inutile d'écrire une comparaison sécurisée contre les attaques temporelles. X-TextMeFlow-Event-Id reste identique d'une nouvelle tentative à l'autre : une contrainte d'unicité sur cette colonne suffit donc à éviter un double traitement. TextMeFlow réessaie les webhooks non délivrés jusqu'à 5 fois avec un délai croissant, et toute réponse autre qu'un 2xx dans les 10 secondes compte comme une tentative échouée. Répondez 200 immédiatement et déportez le vrai travail vers une méthode @Async ou une file d'attente — un gestionnaire lent ressemble, du côté de TextMeFlow, à un délai d'attente dépassé et déclenche des nouvelles tentatives inutiles. La liste complète des en-têtes et la structure des données sont décrites dans la documentation des webhooks ; le mécanisme de signature est détaillé dans vérifier les signatures des webhooks WhatsApp.

En résumé

Une intégration Spring Boot repose sur trois éléments : un appel RestClient avec un jeton bearer, une boucle de nouvelles tentatives qui respecte retryAfterSeconds et une vérification HMAC en temps constant à l'entrée — le tout intégré au framework, sans dépendance supplémentaire à gérer. Commencez gratuitement : en moins d'une heure, votre chemin d'envoi et votre gestionnaire de webhook peuvent tourner.

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