· 2 min · TextMeFlow Team

WhatsApp mit Java (Spring Boot) über die API versenden

Spring Boot bringt bereits alles mit, um mit der TextMeFlow-API zu sprechen — kein SDK von Drittanbietern, keine Codegenerierung. RestClient (seit Spring Framework 6.1 integriert) übernimmt das Versenden, eine kleine Retry-Schleife fängt Rate Limits ab, und javax.crypto.Mac prüft eingehende Webhooks. Dieser Leitfaden geht alle drei durch, mit Code, den du direkt in eine Service-Klasse einsetzen kannst.

Bevor du beginnst

  1. Erstelle ein kostenloses TextMeFlow-Konto — 50 Nachrichten pro Monat, dauerhaft, ohne Kreditkarte und ohne Meta-Business-Verifizierung.
  2. Scanne den QR-Code im Portal mit dem Smartphone, auf dem die WhatsApp-Nummer liegt, von der du versenden willst.
  3. Kopiere deinen API-Schlüssel aus dem Dashboard.

Die vollständige Endpoint-Referenz findest du unter /de/docs/api; alles Folgende bezieht sich auf POST /v1/messages.

Eine Nachricht versenden

Ein minimaler Client besteht aus einer RestClient-Bean, einem Record für den Request-Body und einem Bearer-Token:

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);
    }
}

Halte das Feld to im E.164-Format (+ und Landesvorwahl) — alles andere wird mit einem 422 abgelehnt. mediaUrl ist optional und akzeptiert jede öffentlich erreichbare Datei bis 100 MB (Bild, PDF, Sprachnachricht); lasse es null für eine reine Textnachricht. Eine 202-Antwort bedeutet, dass die Nachricht in der Warteschlange steht, noch nicht, dass sie zugestellt wurde — mit der messageId aus der Antwort prüfst du später den echten Status.

Bei 429 erneut versuchen, ohne die API zu bombardieren

TextMeFlow setzt bewusst Rate Limits — ein Burst-Limit pro Minute und eine Stundenobergrenze je Plan, beschrieben auf der Seite zu den Rate Limits. Die Antwort bei einem 429 enthält reason (burst_exceeded oder hourly_exceeded) und retryAfterSeconds, du musst die Wartezeit also nicht raten:

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

Fünf Versuche reichen in der Praxis völlig aus. Indem du die vorgeschlagene Wartezeit mit der Versuchsnummer multiplizierst, baust du einen Sicherheitspuffer auf das ein, was dir die API bereits mitgeteilt hat — statt auf ein festes Thread.sleep(5000) zu setzen, das entweder Zeit verschwendet oder zu früh erneut versucht. Die vollständige Abwägung zwischen dem Pollen von GET /v1/messages/{id} und dem Vertrauen auf Webhooks für den Zustellstatus findest du im Leitfaden zu Rate Limits und Nachrichtenstatus.

Antworten empfangen: ein signierter Webhook-Handler

Jede eingehende WhatsApp-Antwort wird per POST an den Endpunkt gesendet, den du unter /admin/webhook einrichtest, signiert mit X-TextMeFlow-Signature: sha256=<hex> — ein HMAC-SHA256 des rohen Request-Bodys mit dem Secret, das dir bei der Erstellung nur einmal angezeigt wird. Die rohen Bytes zu binden (statt eines bereits geparsten DTOs) ist entscheidend, damit die Signaturprüfung gültig bleibt:

@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, danach an einen asynchronen Handler übergeben.
        return ResponseEntity.ok().build();
    }
}

MessageDigest.isEqual läuft in konstanter Zeit, du musst also keinen separaten zeitsicheren Vergleich schreiben. X-TextMeFlow-Event-Id bleibt bei jedem Retry gleich, eine Unique-Constraint auf dieser Spalte reicht also, um doppelte Verarbeitung zu vermeiden: TextMeFlow versucht nicht zugestellte Webhooks bis zu 5-mal erneut mit steigendem Backoff, und alles außer einem 2xx innerhalb von 10 Sekunden zählt als fehlgeschlagener Versuch. Antworte sofort mit 200 und verschiebe die eigentliche Arbeit in eine @Async-Methode oder eine Queue — ein langsamer Handler sieht aus Sicht von TextMeFlow genau wie ein Timeout aus und wird unnötig erneut ausgelöst. Die vollständige Liste der Header und die Payload-Struktur findest du in der Webhook-Dokumentation; die Funktionsweise der Signatur wird ausführlicher in WhatsApp-Webhook-Signaturen verifizieren erklärt.

Fazit

Eine Spring-Boot-Integration braucht drei Dinge: einen RestClient-Aufruf mit Bearer-Token, eine Retry-Schleife, die retryAfterSeconds respektiert, und eine zeitkonstante HMAC-Prüfung für eingehende Daten — alles im Framework integriert, ohne zusätzliche Abhängigkeit. Jetzt kostenlos starten und du hast Sende-Pfad und Webhook-Handler innerhalb einer Stunde am 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