· 3 min · TextMeFlow Team

Envoyer un message WhatsApp avec Go (Golang) via l'API

La bibliothèque standard de Go contient déjà tout ce qu'il faut pour dialoguer avec l'API TextMeFlow — pas de SDK, pas de génération de code, pas de client HTTP tiers. net/http, encoding/json et crypto/hmac suffisent pour envoyer des messages, gérer les limites de débit et vérifier les webhooks entrants. Ce guide passe en revue les trois, avec du code que vous pouvez intégrer tel quel dans un 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 à une struct, un corps sérialisé et un jeton bearer :

package textmeflow

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

type SendRequest struct {
	To      string `json:"to"`
	Text    string `json:"text,omitempty"`
	MediaURL string `json:"media_url,omitempty"`
}

type SendResponse struct {
	MessageID string `json:"message_id"`
	Status    string `json:"status"`
}

func Send(apiKey string, msg SendRequest) (*SendResponse, error) {
	body, err := json.Marshal(msg)
	if err != nil {
		return nil, err
	}

	req, err := http.NewRequest(http.MethodPost, "https://api.textmeflow.eu/v1/messages", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+apiKey)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusAccepted {
		return nil, fmt.Errorf("textmeflow: unexpected status %d", resp.StatusCode)
	}

	var out SendResponse
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, err
	}
	return &out, nil
}

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 vide 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 message_id 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 retry_after_seconds : inutile donc de deviner le délai d'attente :

func SendWithRetry(apiKey string, msg SendRequest, maxAttempts int) (*SendResponse, error) {
	var last error
	for attempt := 1; attempt <= maxAttempts; attempt++ {
		body, _ := json.Marshal(msg)
		req, _ := http.NewRequest(http.MethodPost, "https://api.textmeflow.eu/v1/messages", bytes.NewReader(body))
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("Authorization", "Bearer "+apiKey)

		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			return nil, err
		}

		if resp.StatusCode == http.StatusTooManyRequests {
			var rl struct {
				Reason            string `json:"reason"`
				RetryAfterSeconds int    `json:"retry_after_seconds"`
			}
			json.NewDecoder(resp.Body).Decode(&rl)
			resp.Body.Close()
			last = fmt.Errorf("rate limited: %s", rl.Reason)
			time.Sleep(time.Duration(rl.RetryAfterSeconds*attempt) * time.Second)
			continue
		}

		defer resp.Body.Close()
		var out SendResponse
		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
			return nil, err
		}
		return &out, nil
	}
	return nil, fmt.Errorf("gave up after %d attempts: %w", maxAttempts, last)
}

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 une boucle sleep(5) 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. Le package crypto/hmac de Go intègre un Equal en temps constant : inutile d'écrire une comparaison sécurisée contre les attaques temporelles :

func webhookHandler(secret []byte) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		raw, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}

		mac := hmac.New(sha256.New, secret)
		mac.Write(raw)
		expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
		received := r.Header.Get("X-TextMeFlow-Signature")

		if !hmac.Equal([]byte(expected), []byte(received)) {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}

		eventID := r.Header.Get("X-TextMeFlow-Event-Id")
		// INSERT ... ON CONFLICT (event_id) DO NOTHING, puis traitement asynchrone.
		w.WriteHeader(http.StatusOK)
	}
}

Lisez le corps avec io.ReadAll avant que tout middleware de routeur ne le réencode — hacher un corps JSON re-sérialisé plutôt que les octets d'origine est la façon la plus courante de faire échouer cette vérification sans que personne ne s'en aperçoive. 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 effectuez le vrai travail dans une goroutine ou une file d'attente, pas en ligne — 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 Go repose sur trois éléments : un POST avec un jeton bearer, une boucle de nouvelles tentatives qui respecte retry_after_seconds et une vérification HMAC à l'entrée — le tout avec la bibliothèque standard, sans dépendance à intégrer. 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