Envoyez des messages WhatsApp depuis votre application

Un appel HTTP authentifié, et le message part sur le numéro WhatsApp Business de votre client — avec son opt-in vérifié, sa fenêtre de 24 h respectée, son palier d'envoi tenu, et le message visible dans l'inbox de son équipe. Vous n'avez ni jeton Meta à manipuler, ni règle de conformité à réimplémenter.

Contrat public et stable : les évolutions se font par ajout, jamais par rupture. Cette page couvre les deux surfaces publiques de TEERAL — envoyer un message que vous décidez, puis signaler un fait métier dont le tenant décide la réponse. Commencez par la première, c'est presque toujours celle que vous cherchez.

01Envoyer un message depuis votre application

Deux surfaces publiques cohabitent, et elles ne servent pas le même besoin. Choisir la mauvaise se paie en heures perdues, donc la distinction est ici, avant tout le reste.

Ce que vous pouvez envoyer, et à qui. Un template utilitaire ou d'authentification — OTP, confirmation, suivi, rappel — part vers n'importe quel numéro, à tout moment, sans condition. Un texte libre exige que le client vous ait écrit dans les 24 h. Un template marketing exige son consentement. Ces trois règles sont celles de Meta, pas celles de TEERAL, et elles sont appliquées à chaque appel.

Ce que l'API d'envoi vous épargne, et que l'API Cloud de Meta en direct ne vous épargne pas : le jeton WhatsApp reste chez TEERAL, l'opt-in du contact est vérifié, la fenêtre de 24 h est appliquée, le palier d'envoi et la qualité du numéro sont respectés, le message apparaît dans l'inbox de l'équipe, et le compteur de facturation Meta reste juste.

02Clé d'API

L'administrateur de l'espace crée votre clé dans Paramètres → Développeurs, bloc « Envoyer des messages ». Elle s'affiche une seule fois : TEERAL n'en conserve que l'empreinte, personne ne peut la relire, pas même le support.

POST /api/v1/messages HTTP/1.1
Authorization: Bearer sk_a3f9…
Content-Type: application/json
Idempotency-Key: commande-812-confirmation

Une clé par application. La révoquer coupe cette intégration à la seconde, sans toucher aux autres.

03Corps de la requête

Un seul endpoint, discriminé par type. Le destinataire est toujours un numéro au format international.

{
  "to": "+221771112233",
  "type": "text",
  "text": "Votre colis part demain matin."
}

{
  "to": "+221771112233",
  "type": "template",
  "template": {
    "name": "confirmation_commande",
    "language": "fr",
    "variables": ["Awa", "12 500 XOF"],
    "buttons": [{ "index": 0, "value": "CMD-812" }]
  }
}

Le template est désigné par son nom et sa langue, tels qu'ils existent chez Meta. Les variables remplissent le corps dans l'ordre ; buttons ne sert qu'aux boutons dont le lien contient une variable, et attend le fragment qui la remplace, pas l'adresse complète.

{
  "to": "+221771112233",
  "type": "image",          // image | video | audio | document
  "media": {
    "url": "https://cdn.exemple.sn/colis-812.jpg",
    "caption": "Votre colis est prêt"
  }
}

TEERAL va chercher le fichier à cette adresse, en garde une copie pour que l'agent voie ce que son client a reçu, puis l'envoie. L'adresse doit être en HTTPS public (port 443 ou 8443) ; jusqu'à trois redirections sont suivies, chacune revérifiée. Les types et les tailles sont ceux que WhatsApp accepte : 5 Mo pour une image, 16 Mo pour une vidéo ou un audio, 100 Mo pour un document. Une légende sur un audio est refusée — WhatsApp ne l'affiche pas, et la perdre en silence serait pire.

04Mettre au point sans écrire à personne

Ajoutez "dry_run": true et tout se déroule pour de vrai : authentification, validation du corps, résolution du template, verdict complet des règles d'envoi. La réponse dit ce qui serait parti, avec le même code de refus le cas échéant. Rien n'est créé, rien ne part chez Meta, rien n'apparaît dans l'inbox, rien n'est facturé.

200 {
  "dry_run": true,
  "would_send": true,
  "to": "221771112233"
}

05Codes de refus

Chaque refus porte un error stable dans le corps de la réponse. Branchez votre logique sur ce code, jamais sur la phrase qui l'accompagne : le code est un engagement, la phrase peut changer.

409 {
  "error": "contact_opted_out",
  "message": "This contact opted out of marketing messages."
}

06Suivre le sort d'un message

Un envoi accepté rend 201 avec l'identifiant TEERAL du message et son wamid Meta.

201 {
  "id": "7b3e…",
  "status": "sent",
  "wamid": "wamid.HBgABCD…"
}

Deux façons de connaître la suite, au choix. À la demande : GET /api/v1/messages/{id} rend le statut et les horodatages d'envoi, de livraison et de lecture. En temps réel : déclarez une URL de retour sur votre clé, et TEERAL y postera chaque changement.

POST /votre-endpoint HTTP/1.1
x-teeral-event: message.delivered
x-teeral-signature: sha256=…

{
  "version": "1",
  "event_id": "7b3e…:delivered",
  "type": "message.delivered",
  "occurred_at": "2026-08-26T09:59:30.000Z",
  "data": { "message_id": "7b3e…", "wamid": "wamid.HBgABCD…" }
}

Quatre types : message.sent, message.delivered, message.read, message.failed — un par transition, pour que vous branchiez un switch et non une cascade de conditions. La signature suit exactement le même schéma que les Événements TEERAL décrits plus bas : si vous avez déjà écrit ce code, il fonctionne ici sans une ligne de plus.

07Rythme, doublons et garanties

• Rythme. Calé sur le palier d'envoi du numéro, avec une réserve pour les salves courtes. Un dépassement rend 429 rate_limited et un Retry-After — respectez-le plutôt que de boucler.
• Corps. 128 Ko au maximum. Un texte est plafonné à 4 096 caractères, une légende à 1 024.
• Contact inconnu. Créé automatiquement : aucune étape préalable n'est nécessaire pour confirmer la commande d'un nouveau client.
• Visibilité. Vos messages apparaissent dans l'inbox de l'équipe, identifiés comme venant de l'API. C'est voulu : l'agent qui répond doit savoir ce que votre application a déjà dit.

Signaler un fait métier

L'autre besoin. Votre système signale un fait : une commande passée, une livraison expédiée, un ticket résolu. TEERAL le reçoit, choisit le scénario que le tenant a activé, et envoie le message. Vous poussez ; TEERAL encaisse — et c'est lui, pas vous, qui décide du contenu.

L'ingestion est servie par l'application TEERAL, pas par son Directus : ce sont deux hôtes distincts.

08Démarrage rapide

Trois étapes, du premier événement au message reçu.

• Créez une source. Dans votre espace TEERAL, écran Paramètres → Développeurs, bloc « Signaler vos événements ». Notez l'identifiant de source (src_…), et le secret : le secret n'est affiché qu'une seule fois.
• Signez et postez votre premier événement sur /api/events. Vous recevez 202 avec handled.
• Vérifiez le journal des exécutions dans TEERAL. Tant qu'un envoi réel n'est pas activé, l'exécuteur reste en dry-run, aucun message ne part, vous validez sans risque.

09Endpoint & authentification

Une seule route reçoit tout. L'URL exacte, l'identifiant de source et le secret figurent dans votre espace TEERAL : recopiez-les de là, pas de cette page.

POST /api/events HTTP/1.1
Content-Type: application/json
x-teeral-source: src_b1f84be9c5c07f2300fe34ce18ae3d97
x-teeral-signature: sha256=9f86d081884c7d659a2feaa0c55ad015…

Aucun secret ne circule dans l'URL : il ne doit jamais finir dans un journal serveur ou une capture d'écran. Le secret est régénérable à tout moment, source par source, sans toucher à vos autres intégrations.

10Signature HMAC

La signature est un HMAC-SHA256 du corps brut (les octets exactement tels qu'ils partent) avec votre secret comme clé, en hexadécimal minuscule, préfixé de sha256=.

import { createHmac } from "node:crypto";

// sérialisé UNE fois, c'est cette chaîne exacte qui part
const body = JSON.stringify(payload);
const signature = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");

await fetch(`${TEERAL_URL}/api/events`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-teeral-source": sourceKey,
    "x-teeral-signature": signature,
  },
  body,                // le MÊME corps
});

11Corps de la requête

{
  "version": "1",
  "event_id": "evt_2026_07_21_88213",
  "type": "order.created",
  "object_ref": "CMD-20260721-0042",
  "contact_phone": "221771112233",
  "contact_name": "Awa Diop",
  "occurred_at": "2026-07-21T14:32:00Z",
  "data": { "amount_xof": 15000 }
}

12event_id vs object_ref

C'est l'erreur qui coûte le plus cher, et elle est silencieuse. Prenez une minute ici.

Une même commande produit plusieurs événements au cours de sa vie : ils partagent le même object_ref et ont chacun un event_id distinct.

event_id doit aussi rester stable entre deux tentatives d'envoi du même fait. C'est ce qui rend un rejeu sûr : si votre requête échoue en réseau et que vous la rejouez, le même event_id garantit qu'aucun message en double ne part chez votre client.

13Types d'événements

Un type inconnu de TEERAL est accepté et journalisé sans rien déclencher. Vous pouvez donc émettre plus large que ce que TEERAL consomme aujourd'hui, sans rien changer quand un nouveau scénario sortira.

Statuts de commande : votre vocabulaire

data.status accepte n'importe quelle chaîne non vide : confirmed, preparing, livré… TEERAL ne traduit rien et n'impose aucune liste. C'est dans l'automatisation, côté espace TEERAL, que se déclarent les statuts qui déclenchent un message : match exact, insensible à la casse, espaces ignorés. Un statut qui ne matche aucune automatisation active est journalisé et répond 202 avec handled: false : aucun message ne part.

{
  "version": "1",
  "event_id": "CMD-0042:confirmed:2026-07-24T10:05:00Z",
  "type": "order.status_changed",
  "object_ref": "CMD-0042",
  "contact_phone": "221771112233",
  "data": { "status": "confirmed" }
}
// Une automatisation configurée sur le statut "confirmed" envoie
// son template ; un statut sans automatisation → 202, handled: false.

Pour le suivi interne de la commande (fiche contact, historique), TEERAL reconnaît en plus le cycle created → prepared → shipped → in_transit → delivered, linéaire et sans retour. Un statut hors de ce cycle est conservé au journal sans faire avancer la fiche, cela n'empêche aucun envoi.

14Codes de réponse

Codes de refus en 400

version_unsupported event_id_missing type_invalid contact_phone_missing contact_phone_invalid occurred_at_invalid data_not_object invalid_json

15Garanties & limites

Ce que TEERAL garantit

• Réponse immédiate. L'ingestion authentifie, valide, enregistre, répond. Aucun appel à WhatsApp pendant votre requête : votre système n'attend jamais Meta.
• Rejeu sans danger. Le même event_id ne produit ni second événement ni second message.
• Isolation. Le tenant est déduit de votre source authentifiée, jamais d'un champ du corps.

Ce que TEERAL ne fait pas

• Aucun retour de statut vers votre système : TEERAL ne vous notifie pas de la délivrance du message.
• Aucune traduction depuis le format de votre outil : l'adaptateur vers ce contrat vous appartient.
• Un événement sans numéro exploitable est refusé. Un fait qui ne désigne personne de joignable ne peut rien déclencher.

16Tester l'intégration

Validez en deux temps, sans jamais risquer un envoi accidentel au client.

• Dry-run d'abord. Tant que l'envoi réel n'est pas activé côté TEERAL, l'exécuteur journalise sans envoyer. Émettez, vérifiez 202 + handled: true, et lisez le journal : un run dry-run y apparaît.
• Puis réel. Une fois l'envoi activé, réémettez avec un event_id différent (sinon rejeu neutre) vers un destinataire opt-in. Un humain confirme la réception.

17Recevoir les événements TEERAL

Le sens inverse. Quand un fait se produit dans TEERAL (aujourd'hui la soumission d'un Formulaire par un client sur WhatsApp) TEERAL le POSTe vers l'URL que vous déclarez. Même enveloppe versionnée, même schéma de signature : le code que vous avez écrit pour signer vos envois vous sert à vérifier ceux de TEERAL.

Vous déclarez cette URL (appelée la Destination) dans votre espace TEERAL, écran Paramètres → Développeurs, bloc « Recevoir les Événements TEERAL ». Une seule par espace. Le secret de signature y est affiché une seule fois, à la déclaration et à chaque régénération ; aucun écran ni aucune réponse d'API ne le redonne ensuite.

Ces règles sont revérifiées à chaque tentative, pas seulement à l'enregistrement : une URL modifiée après coup ne contourne rien.

18Enveloppe & en-têtes

POST /votre-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: TEERAL-Webhooks/1 (+https://teeral.app/developpeurs)
x-teeral-event: form.submitted
x-teeral-delivery: 4c1f2a7e-3b90-4d55-8e21-1f6c0a93bd77.3
x-teeral-signature: sha256=9f86d081884c7d659a2feaa0c55ad015…

Corps

{
  "version": "1",
  "event_id": "9f1c0b2e-7d44-4a1f-9b3e-2c8a5f0d61aa",
  "type": "form.submitted",
  "object_ref": "CMD-20260731-0042",
  "occurred_at": "2026-07-31T09:14:22.000Z",
  "contact": {
    "phone": "+221771112233",
    "name": "Awa Diop"
  },
  "data": {
    "form_name": "Demande de rappel",
    "meta_flow_id": "1234567890123456",
    "fields": {
      "ville": "Dakar",
      "rappel_accepte": true
    }
  }
}

data de form.submitted

data de order.received

Émis quand un client envoie un panier depuis le catalogue WhatsApp. C'est une intention d'achat ouverte dans la conversation, pas une commande payée : la confirmation, si elle a lieu, viendra de votre système. object_ref est toujours null : le panier arrive à l'initiative du client, rien ne le précède.

19Vérifier la signature

Strictement le même schéma qu'à l'entrée : HMAC-SHA256 du corps brut, votre secret de Destination comme clé, hexadécimal minuscule, préfixé de sha256=.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody : un Buffer ou la chaine EXACTE recue, jamais un objet reserialise
function verifyTeeralSignature(rawBody, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = Buffer.from(header ?? "", "utf8");
  const awaited = Buffer.from(expected, "utf8");
  // longueurs comparees d'abord : timingSafeEqual leve si elles different
  return received.length === awaited.length && timingSafeEqual(received, awaited);
}

app.post("/teeral", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyTeeralSignature(req.body, req.get("x-teeral-signature"), process.env.TEERAL_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  enqueue(event);           // le travail se fait APRES la reponse
  res.sendStatus(204);
});

20Retentatives & déduplication

Ce qui compte comme une livraison réussie

Une réponse 2xx en moins de 10 secondes. Le corps de votre réponse est lu de façon plafonnée et n'entre dans aucune décision : répondez 204 et faites le travail après. Une redirection 3xx n'est pas suivie : déclarez l'URL finale.

La cadence

Huit retentatives, de plus en plus espacées, après la livraison immédiate :

1 min 5 min 15 min 1 h 3 h 6 h 12 h 24 h

La dernière tombe environ 47 h après le fait. La promesse est donc chiffrable : votre endpoint peut être indisponible 24 h d'affilée sans qu'un seul fait soit perdu. Passé la huitième, l'événement est abandonné et l'administrateur de l'espace reçoit une notification.

Déduplication et ordre

• Dédupliquez par event_id. Il ne change pas d'une tentative à l'autre. Enregistrez-le et ignorez un fait déjà vu : c'est ce qui rend le rejeu inoffensif.
• Le rejeu est possible, et se neutralise par event_id. Une réponse perdue en chemin fait recommencer TEERAL alors que vous aviez déjà traité le fait. La signature seule ne l'empêche pas : elle prouve l'origine, pas la nouveauté.
• Aucune garantie d'ordre. Deux faits proches peuvent vous arriver dans le désordre, et un fait retenté arrive forcément après des faits plus récents. Fiez-vous à occurred_at, jamais à l'ordre de réception.
• Traitez de façon idempotente. Répondre 2xx vite puis travailler en tâche de fond est le bon patron : les 10 secondes ne sont pas un budget de traitement.