Envoyer un message

POST /v1/messages : envoyer un template approuvé, avec idempotence et remboursement sur échec.

Envoyer un message template

Note — Template ou réponse : lequel utiliser ?
Répondre à un client qui vous a écrit dans les 24 heures ? Utilisez le texte libre, gratuit, via POST /v1/messages/reply. Envoyer un message à l'initiative de l'entreprise — diffusion, relance, notification proactive, ou tout message hors de cette fenêtre de 24h ? WhatsApp impose alors un template pré-approuvé par Meta, envoyé avec POST /v1/messages décrit ci-dessous.

POST /v1/messages — scope messages:send

Envoie un template APPROVED à un destinataire. Retourne 202. Le frais de plateforme est débité avant l'envoi ; si Meta rejette, il est automatiquement remboursé.

Paramètres

Paramètre	Type	Requis	Description
to	string	Oui	Destinataire au format E.164, ex. +237699123456.
template.name	string	Oui	Nom d'un template APPROVED.
template.language	string	Oui	Code langue, ex. en, fr, en_US.
template.variables	string[]	Non	Remplit {{1}}…{{n}} dans l'ordre.
template.header_image_url	string	Non	Uniquement si le template a un en-tête IMAGE.
template.header_document_url	string	Non	Uniquement si le template a un en-tête DOCUMENT (ex. un PDF). Jamais en même temps que header_image_url.
template.header_document_filename	string	Non	Nom de fichier affiché dans la bulle WhatsApp, ex. bulletin.pdf.
from	string	Non	phone_number_id du numéro émetteur (voir GET /v1/numbers). Omis = numéro par défaut du compte.
idempotency_key	string	Non	Rejouer la même clé renvoie le résultat d'origine (retries sûrs).

Note — Plusieurs numéros
Votre compte peut connecter plusieurs numéros (facturation commune, un seul pot de crédits). Précisez `from` pour choisir l'émetteur ; sinon le numéro par défaut est utilisé. Le template doit être APPROVED sur la WABA de CE numéro.

Requête

curl -X POST https://wa-api.geskap.com/v1/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+237699123456",
    "template": { "name": "order_update", "language": "en", "variables": ["Jean", "#8842"] },
    "idempotency_key": "order-8842"
  }'

Réponse (202)

{
  "id": "6f1c…",
  "status": "sent",
  "wa_message_id": "wamid…",
  "to": "2376****3456",
  "credits_charged": 1,
  "credits_remaining": 4197,
  "created_at": "2026-08-04T09:14:07Z"
}

Note — En-têtes de réponse
La réponse pose X-Credits-Remaining (solde après débit). Le destinataire est masqué dans les réponses et les logs (2376****3456).

Astuce — Idempotence
Passez une idempotency_key stable (ex. l'ID de commande). Rejouer la même clé renvoie le résultat d'origine sans réenvoyer — vos retours-arrière et reprises ne double-envoient jamais.