Branchez votre système aux automatisations WhatsApp

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 bon scénario et envoie le message WhatsApp au client. Vous poussez ; TEERAL encaisse.

Contrat public et stable : les évolutions se font par ajout, jamais par rupture. L'ingestion est servie par l'application TEERAL, pas par son Directus — ce sont deux hôtes distincts.

01Démarrage rapide

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

• Créez une source. Dans votre espace TEERAL, écran Automatisations → Sources d'é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.

02Endpoint & 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.

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

04Corps 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 }
}

05event_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.

06Types 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.

07Codes 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

08Garanties & 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.

09Tester 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.