Documentation API 10nastie

Démarrer en trois étapes

1. Connectez votre numéro WhatsApp depuis votre tableau de bord, puis créez une clé API dans Paramètres > API.
2. Choisissez un modèle de message déjà validé, par exemple confirmation_commande.
3. Envoyez votre premier message :

curl -X POST https://api.[votre-domaine]/v1/messages \
  -H "Authorization: Bearer sk_test_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2250700000000",
    "template": "confirmation_commande",
    "variables": ["Aminata", "4521", "15 000"]
  }'

Authentification

Chaque requête doit porter votre clé API dans l'en-tête Authorization, sous la forme Bearer <clé>. Une requête sans clé, ou avec une clé révoquée, reçoit l'erreur 401 invalid_api_key.

Authorization: Bearer sk_live_VOTRE_CLE

Vous pouvez créer plusieurs clés, par exemple une par site ou par environnement, et en révoquer une à tout moment depuis Paramètres > API. Une clé n'est affichée qu'une seule fois, à sa création.

Ne pas envoyer deux fois

Ajoutez un en-tête Idempotency-Key unique par envoi, par exemple commande-4521-confirmation. Si votre serveur renvoie la même requête après une coupure réseau, l'API renvoie la première réponse sans renvoyer le message. Une clé reste mémorisée 24 heures.

Réutiliser la même clé avec un contenu différent renvoie 409 idempotency_conflict.

Catégories

La catégorie détermine le prix et les règles d'usage. WhatsApp peut reclasser un modèle s'il ne correspond pas à la catégorie choisie.

Événements

Format

{
  "id": "evt_01J8Q5M2XR",
  "type": "message.delivered",
  "created_at": "2026-09-27T10:42:21Z",
  "data": {
    "message_id": "msg_01J8Q2Z7K4",
    "to": "+2250700000000",
    "status": "delivered",
    "reference": "commande-4521"
  }
}

Pour message.received, data contient l'expéditeur (from), le type (text, image, document, audio, location, button), le contenu et, s'il s'agit d'une réponse, l'identifiant du message d'origine (context.message_id).

Vérifier la signature

Chaque requête porte deux en-têtes : X-Signature-Timestamp et X-Signature, qui vaut sha256= suivi du HMAC-SHA256 de timestamp.corps_brut avec votre secret. Rejetez toute requête dont la signature ne correspond pas, ou dont l'horodatage a plus de 5 minutes.

const crypto = require("crypto");

function signatureValide(corpsBrut, timestamp, signature, secret) {
  const attendu = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + corpsBrut)
    .digest("hex");
  const recent = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return recent && crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(signature));
}

$attendu = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpsBrut, $secret);
$valide = hash_equals($attendu, $signature) && abs(time() - (int) $timestamp) < 300;

Répondre et gérer les relances

Répondez par un code 2xx en moins de 5 secondes, puis traitez l'événement en arrière-plan. Sans réponse 2xx, nous renvoyons l'événement jusqu'à 8 fois sur 24 heures, à intervalles croissants. Après 24 heures d'échecs, le webhook est désactivé et vous êtes prévenu par e-mail.

Un même événement peut arriver deux fois, et pas toujours dans l'ordre : utilisez son id pour ignorer les doublons, et ne faites jamais reculer un statut (un message read ne redevient pas delivered).

Destinataires par 24 heures (règle WhatsApp)

WhatsApp limite le nombre de personnes différentes à qui vous pouvez écrire en premier sur 24 heures glissantes. Les messages envoyés à un client qui vous a écrit dans les dernières 24 heures ne comptent pas, et un même client ne compte qu'une fois, même s'il reçoit plusieurs messages.

La limite est partagée entre tous les numéros de votre compte. Au-delà, l'API renvoie 429 messaging_limit_reached : réessayez après l'heure indiquée dans le champ retry_after. Le webhook limit.updated vous prévient quand votre niveau change.

Requêtes par seconde

Chaque clé peut faire 20 requêtes par seconde. Au-delà, l'API renvoie 429 rate_limited avec l'en-tête Retry-After. Pour les gros volumes, utilisez POST /messages/batch plutôt que des envois un par un.

Erreurs

En cas d'erreur, l'API renvoie un code HTTP et un objet error avec un code stable, que votre programme peut tester, et un message en français, destiné à vos développeurs.

{
  "error": {
    "code": "template_not_approved",
    "message": "Le modèle livraison_en_cours est en cours d'examen par WhatsApp.",
    "request_id": "req_01J8Q6T0PZ"
  }
}

Communiquez le request_id au support : il nous permet de retrouver votre requête.

Échecs après acceptation

Un message accepté (202) peut encore échouer à la livraison. Vous le saurez par le webhook message.failed, dont le champ error.code peut valoir :

Ces messages ne sont pas décomptés de votre forfait.

Quand réessayer

Réessayez uniquement les erreurs 429, 500 et 502, avec un délai qui double à chaque essai (1 s, 2 s, 4 s…) et la même Idempotency-Key. Les erreurs 4xx restantes ne se corrigent pas en réessayant.

Forfaits et décompte

Chaque forfait API inclut un nombre de messages par mois, payé en FCFA par Orange Money, MTN ou Wave. Seuls les messages livrés sont décomptés ; les messages que vos clients vous envoient sont gratuits.

Tous les forfaits incluent la documentation, les webhooks, l'extension WooCommerce et 1 000 réponses libres par mois dans la fenêtre de 24 heures.

Au-delà du forfait

Les envois supplémentaires sont déduits de votre solde de recharge :

Pays des destinataires

Un prix unique s'applique à toute l'Afrique de l'Ouest et du Centre. Un message envoyé hors d'Afrique compte pour 4 messages ; le champ units de chaque réponse indique ce décompte.

Report et validité

Les messages non utilisés passent sur le mois suivant si vous renouvelez votre forfait, puis expirent. Les recharges restent valables 3 mois.

Entreprises non vérifiées

Sans documents d'entreprise, vos envois sont limités à 250 destinataires par jour (voir Limites). C'est suffisant pour l'API Essentiel. Pour l'API Pro, nous vous accompagnons pour faire vérifier votre entreprise et lever cette limite.

Extension WooCommerce

L'extension WordPress envoie automatiquement vos messages WhatsApp à chaque étape d'une commande WooCommerce, sans écrire de code.

Installation

1. Téléchargez l'extension depuis votre tableau de bord, dans Paramètres > API > WooCommerce.
2. Dans WordPress, ouvrez Extensions > Ajouter > Téléverser une extension, choisissez le fichier, puis activez-la.
3. Ouvrez WooCommerce > WhatsApp et collez votre clé API de production.
4. Choisissez l'indicatif par défaut (+225 pour la Côte d'Ivoire) : il est ajouté aux numéros saisis sans indicatif par vos clients.
5. Associez un modèle à chaque étape de commande que vous voulez signaler.

Étapes et variables

L'extension utilise le numéro de téléphone de facturation de la commande et envoie chaque message une seule fois par étape, même si le statut est modifié plusieurs fois.

Consentement

L'extension ajoute à la page de paiement une case « Recevoir le suivi de ma commande sur WhatsApp », cochée par défaut pour les messages transactionnels. Si le client la décoche, aucun message ne lui est envoyé. Aucun message marketing n'est envoyé par l'extension.

Journal

WooCommerce > WhatsApp > Journal affiche, pour chaque commande, les messages envoyés et leur statut (envoyé, livré, lu, échec). La même information apparaît dans les notes de la commande.

Bonnes pratiques et règles d'utilisation

La qualité de votre numéro dépend de la façon dont vos clients reçoivent vos messages : trop de blocages ou de signalements font baisser votre limite, puis suspendent vos modèles.

En cas de non-respect, nous pouvons suspendre votre clé API sans préavis. Nous surveillons automatiquement les volumes inhabituels, les baisses de qualité et les modèles suspects, mais nous ne lisons pas vos conversations.

Données personnelles

Les numéros et messages de vos clients sont des données personnelles. Nous les conservons [durée de conservation] puis les supprimons, et vous restez responsable de l'information de vos clients sur l'usage de leur numéro, conformément à la loi ivoirienne sur la protection des données personnelles.

Support et versions

Notre équipe technique répond en français sur WhatsApp au [numéro WhatsApp] et par e-mail à [adresse e-mail], du lundi au samedi de [horaires]. Joignez toujours le request_id de la requête concernée.

L'état du service et les incidents en cours sont publiés sur [page d'état du service].

Versions

La version actuelle est v1, indiquée dans l'adresse de chaque requête. Nous pouvons ajouter des champs aux réponses et de nouveaux événements sans changer de version : votre code doit ignorer les champs qu'il ne connaît pas. Tout changement incompatible fera l'objet d'une nouvelle version, annoncée au moins 90 jours à l'avance.