Se connecterCommencer l’essai gratuit
Meta Tech Provider

Créer un agent IA WhatsApp en Node.js et Python sur un numéro Coexistence

Recevez les messages du numéro soit transférés avec une signature HMAC à vérifier (X-EC-Signature), soit directement depuis le webhook de Meta avec un secret dans l'URL. Ignorez ensuite tout identifiant de message déjà traité, restez silencieux sur une conversation où un écho montre qu'une personne a répondu depuis le téléphone, et envoyez la réponse de votre modèle via la Cloud API uniquement dans les 24 heures suivant le dernier message du client.

easyCoexistence connecte le numéro que l'entreprise continue d'utiliser dans l'application WhatsApp Business à la Cloud API de Meta, fournit à votre code ses identifiants via get_api_credentials, et route les messages directement de Meta vers votre serveur ou via un transfert signé avec les automatisations activées.

5 min

Écart maximal accepté entre le t de la signature et votre horloge ; chaque nouvelle tentative est re-signée avec un t récent.

10 s

Durée d'attente d'un POST transféré pour une réponse 2xx avant que easyCoexistence planifie une nouvelle tentative de cette livraison.

7 days

Durée pendant laquelle Meta réessaie un webhook direct qui n'a pas reçu HTTP 200, ce qui peut livrer deux fois le même message.

24 hours

Fenêtre de service client après le dernier message de l'utilisateur ; au-delà, Meta n'accepte que les messages template.

20 mps

Débit fixe d'un numéro utilisé à la fois avec l'application WhatsApp Business et la Cloud API.

Quelle route un agent codé doit-il utiliser ?

Le mode transféré garde le numéro dans Automatisations : Meta livre à easyCoexistence, les automatisations peuvent toujours s'exécuter, et une copie signée de chaque modification Meta part vers votre URL de transfert. Une variante ne nécessite aucun transfert : une étape « Call my webhook » d'une automatisation envoie le message en POST à votre endpoint et renvoie ce que vous retournez dans {"reply"} sous 20 secondes, avec déduplication, pause téléphone et contrôle des 24 heures pris en charge pour vous.

Le mode direct signifie que Meta envoie son propre webhook directement à votre endpoint, configuré avec set_webhook_destination, et easyCoexistence ne voit jamais les messages. Les automatisations sont désactivées pour ce numéro, donc toutes les protections vous reviennent, de même que l'import de l'historique de 6 mois lorsque la destination est enregistrée dans les 24 heures suivant la connexion. Les exemples ci-dessous gèrent les trois points d'entrée avec un cœur commun.

Forwarded, signedDirect from Meta
Number modeAutomations on (managed)Direct to your server
BodyOne Meta change: id, event, received_at, connection, valueMeta's envelope: object, entry, changes
AuthenticationX-EC-Signature, HMAC-SHA256 with a per-number secretA secret in the URL path
AcknowledgeAny 2xx within 10 secondsHTTP 200; Meta retries other codes
Retries7 attempts over about 33 hoursUp to 7 days
ReplyGraph API, or {"reply"} to a Call my webhook stepGraph API
History importNot requestedRequested if saved within 24 hours of connecting

Que fait l'agent avec un message, en Node.js ?

agent.mjs contient la logique commune aux deux routes. Il enregistre l'heure du dernier message du client, se met en retrait pendant 4 heures sur une conversation lorsqu'un événement smb_message_echoes indique qu'un humain a répondu depuis l'application WhatsApp Business (le réglage que les automatisations easyCoexistence utilisent par défaut), ignore un identifiant de message déjà traité et n'envoie qu'à l'intérieur de la fenêtre de 24 heures. La fenêtre est calculée à partir de l'horodatage du message lui-même, et non de son arrivée chez vous, car une livraison réessayée peut arriver avec plusieurs heures de retard.

Les utilisateurs sont identifiés par BSUID (from_user_id, ou to_user_id sur les échos) avec le numéro de téléphone en secours, et un utilisateur connu seulement par BSUID reçoit sa réponse via recipient au lieu de to. L'appel au modèle utilise n'importe quelle API de complétion de chat compatible OpenAI ; remplacez-la par le SDK de votre fournisseur si vous préférez.

agent.mjs: the shared logic
// agent.mjs: what the agent does with one Meta change, whichever route brought it.
const DAY = 24 * 3600 * 1000;
const PAUSE = 4 * 3600 * 1000;   // quiet time after a person replies (automations default to 4 h)
const seen = new Set();          // handled ids: use Redis or your database in production
const lastInbound = new Map();   // user -> ms of their last message
const quietUntil = new Map();    // user -> ms until which a person has the chat

export function firstTime(id) {
  if (seen.has(id)) return false;
  seen.add(id);
  return true;
}

export async function handleChange(field, value) {
  if (field === "smb_message_echoes") {
    // Someone answered from the WhatsApp Business app: step back on that chat.
    for (const e of value.message_echoes ?? []) {
      quietUntil.set(e.to_user_id ?? e.to, Number(e.timestamp) * 1000 + PAUSE);
    }
    return;
  }
  if (field !== "messages") return;              // statuses ride in value.statuses: ignored here
  for (const m of value.messages ?? []) {
    if (!firstTime(m.id)) continue;               // Meta delivered this message before
    const user = m.from_user_id ?? m.from;        // BSUID first, phone number as fallback
    lastInbound.set(user, Math.max(Number(m.timestamp) * 1000, lastInbound.get(user) ?? 0));
    if ((quietUntil.get(user) ?? 0) > Date.now()) continue; // a person has this chat
    if (m.type !== "text") continue;              // media: fetch it by id first (see the FAQ)
    const reply = await askModel([{ role: "user", content: m.text.body }]);
    if (!reply) continue;
    if (Date.now() - lastInbound.get(user) >= DAY) continue; // window closed: template only
    await sendText({ phone: m.from, bsuid: m.from_user_id }, reply);
  }
}

// Any OpenAI-compatible chat completions API (OpenAI, OpenRouter...).
export async function askModel(turns) {
  const res = await fetch(`${process.env.AI_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.AI_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: process.env.AI_MODEL,
      messages: [{ role: "system", content: process.env.AI_INSTRUCTIONS ?? "Answer briefly." }, ...turns],
    }),
  });
  if (!res.ok) throw new Error(`AI provider answered ${res.status}`);
  const data = await res.json();
  return data.choices?.[0]?.message?.content?.trim() ?? "";
}

// send_endpoint and access_token come from get_api_credentials.
async function sendText({ phone, bsuid }, text) {
  const res = await fetch(process.env.SEND_ENDPOINT, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      recipient_type: "individual",
      ...(phone ? { to: phone } : { recipient: bsuid }), // a BSUID-only user gets recipient
      type: "text",
      text: { body: text.slice(0, 4096) },
    }),
  });
  if (!res.ok) throw new Error(`Graph API answered ${res.status}: ${await res.text()}`);
}

Comment vérifier et router les événements en Node.js ?

server.mjs expose les trois points d'entrée. /ec/forward reçoit les transferts des numéros gérés : il vérifie X-EC-Signature sur les octets bruts avec le secret de transfert du numéro, répond 200 avant tout traitement, et ignore un identifiant de livraison déjà accepté, car une nouvelle tentative porte le même identifiant avec une signature neuve. Le champ event du corps est le nom de champ de Meta et value est la modification Meta, sans changement. /ec/agent répond à une étape « Call my webhook », signée avec le secret de signature propre à cette automatisation, et transforme l'historique en tours de conversation. /meta/:secret est la route directe : elle répond au GET de vérification de Meta avec le hub.challenge brut, et n'accepte les POST que sur le chemin secret.

La clé HMAC est la chaîne complète, préfixe whsec_ compris, en texte UTF-8. express.raw conserve les octets intacts, et sa limite de 5 Mo laisse de la marge pour les payloads de Meta allant jusqu'à 3 Mo.

server.mjs: verification and routes (Express)
// server.mjs: Node 18+, npm i express, then node server.mjs
import crypto from "node:crypto";
import express from "express";
import { askModel, firstTime, handleChange } from "./agent.mjs";

const app = express();

// X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the whole secret.
export function verifyEc(raw, header, secret, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !Buffer.isBuffer(raw) || !secret) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false; // stale or replayed
  const expected = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], "hex"));
}

function sameSecret(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b ?? ""));
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

// Route A, forwarded: a managed number's Forward URL. One Meta change per POST.
app.post("/ec/forward", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_FORWARD_SECRET)) return res.sendStatus(401);
  res.sendStatus(200);                                   // acknowledge inside 10 s, then work
  const d = JSON.parse(req.body.toString("utf8"));
  if (!firstTime(`delivery:${d.id}`)) return;            // a retry of a delivery already taken
  handleChange(d.event, d.value).catch(console.error);   // d.event is the Meta field name
});

// Route A, synchronous: a "Call my webhook" step. Answer {"reply"} within 20 s.
app.post("/ec/agent", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_AUTOMATION_SECRET)) return res.sendStatus(401);
  const step = JSON.parse(req.body.toString("utf8"));
  const turns = step.history.map((h) => ({ role: h.direction === "in" ? "user" : "assistant", content: h.text }));
  while (turns[0]?.role === "assistant") turns.shift();
  if (!turns.length) turns.push({ role: "user", content: step.message?.text ?? "" }); // tests carry no history
  res.json({ reply: await askModel(turns) });            // step.dry_run is true on "Test it"
});

// Route B, direct: Meta's own envelope. The secret path is the credential.
app.get("/meta/:secret", (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === process.env.VERIFY_TOKEN) {
    return res.type("text/plain").send(String(req.query["hub.challenge"]));
  }
  res.sendStatus(403);
});

app.post("/meta/:secret", express.json({ limit: "5mb" }), (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200);                                   // Meta retries anything but 200
  for (const entry of req.body.entry ?? []) {
    for (const change of entry.changes ?? []) handleChange(change.field, change.value).catch(console.error);
  }
});

app.listen(process.env.PORT ?? 3000);

À quoi ressemble le même agent en Python ?

Un seul fichier Flask, avec les trois mêmes routes et les mêmes règles. request.get_data() renvoie le corps brut pour le HMAC, hmac.compare_digest effectue la comparaison à temps constant, et le traitement s'exécute sur un thread d'arrière-plan après le 200, de sorte que ni easyCoexistence ni Meta n'attendent votre modèle. Lancez-le avec flask --app agent run pendant le développement, et derrière gunicorn ou un autre serveur WSGI en production.

L'ensemble et les dictionnaires en mémoire conviennent à un seul processus. Avec plusieurs workers ou instances, déplacez-les vers Redis ou votre base de données, en utilisant une écriture set-if-absent avec expiration pour les identifiants de message, sinon deux workers répondront au même message.

agent.py: the whole agent (Flask)
# agent.py: pip install flask requests, then flask --app agent run
import hashlib, hmac, json, os, re, threading, time
import requests
from flask import Flask, abort, request

app = Flask(__name__)
DAY, PAUSE = 24 * 3600, 4 * 3600
seen, last_inbound, quiet_until = set(), {}, {}  # use Redis or a database in production
lock = threading.Lock()

def verify_ec(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.fullmatch(r"t=([0-9]+),v1=([0-9a-f]{64})", (header or "").strip())
    if not m or not secret or abs(time.time() - int(m[1])) > tolerance:
        return False
    expected = hmac.new(secret.encode(), m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

def first_time(key: str) -> bool:
    with lock:
        if key in seen:
            return False
        seen.add(key)
        return True

def ask_model(turns: list) -> str:  # any OpenAI-compatible chat completions API
    r = requests.post(f"{os.environ['AI_BASE_URL']}/chat/completions", timeout=30,
                      headers={"Authorization": f"Bearer {os.environ['AI_KEY']}"},
                      json={"model": os.environ["AI_MODEL"], "messages": [
                          {"role": "system", "content": os.environ.get("AI_INSTRUCTIONS", "Answer briefly.")}, *turns]})
    r.raise_for_status()
    return (r.json()["choices"][0]["message"]["content"] or "").strip()

def send_text(phone, bsuid, text: str) -> None:  # SEND_ENDPOINT and WA_TOKEN: get_api_credentials
    to = {"to": phone} if phone else {"recipient": bsuid}
    r = requests.post(os.environ["SEND_ENDPOINT"], timeout=15,
                      headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
                      json={"messaging_product": "whatsapp", "recipient_type": "individual", **to,
                            "type": "text", "text": {"body": text[:4096]}})
    r.raise_for_status()

def handle_change(field: str, value: dict) -> None:
    if field == "smb_message_echoes":  # a person answered from the app: step back
        for e in value.get("message_echoes", []):
            quiet_until[e.get("to_user_id") or e.get("to")] = int(e["timestamp"]) + PAUSE
        return
    if field != "messages":
        return
    for m in value.get("messages", []):
        if not first_time(m["id"]):  # Meta delivered this message before
            continue
        user = m.get("from_user_id") or m.get("from")
        last_inbound[user] = max(int(m["timestamp"]), last_inbound.get(user, 0))
        if quiet_until.get(user, 0) > time.time() or m.get("type") != "text":
            continue
        reply = ask_model([{"role": "user", "content": m["text"]["body"]}])
        if reply and time.time() - last_inbound[user] < DAY:  # past 24 h: template only
            send_text(m.get("from"), m.get("from_user_id"), reply)

def later(field, value):
    threading.Thread(target=handle_change, args=(field, value), daemon=True).start()

@app.post("/ec/forward")  # route A: a managed number's Forward URL
def forward():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_FORWARD_SECRET"]):
        abort(401)
    d = json.loads(raw)
    if first_time("delivery:" + d["id"]):  # skip retries of a delivery already taken
        later(d["event"], d["value"])
    return "", 200

@app.post("/ec/agent")  # route A: a "Call my webhook" step, answer within 20 s
def agent_step():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_AUTOMATION_SECRET"]):
        abort(401)
    step = json.loads(raw)
    turns = [{"role": "user" if h["direction"] == "in" else "assistant", "content": h["text"]}
             for h in step["history"]]
    while turns and turns[0]["role"] == "assistant":
        turns.pop(0)
    turns = turns or [{"role": "user", "content": step["message"]["text"] or ""}]
    return {"reply": ask_model(turns)}

@app.get("/meta/<secret>")  # route B: Meta's GET handshake
def meta_handshake(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    if (request.args.get("hub.mode") == "subscribe"
            and request.args.get("hub.verify_token") == os.environ["VERIFY_TOKEN"]):
        return request.args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
    abort(403)

@app.post("/meta/<secret>")  # route B: Meta's envelope, straight from Meta
def meta_events(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    for entry in (request.get_json(silent=True) or {}).get("entry", []):
        for change in entry.get("changes", []):
            later(change.get("field"), change.get("value", {}))
    return "", 200

Comment éviter les réponses en double ?

Les doublons ont six causes courantes ; les exemples ci-dessus traitent les cinq premières :

  • Les nouvelles tentatives de Meta. Un webhook direct est réessayé pendant 7 jours au maximum après toute réponse autre que HTTP 200 ; conservez un stock d'identifiants de message et ignorez ceux déjà traités.
  • Nouvelles tentatives de transfert. easyCoexistence réessaie une livraison qui n'a pas reçu de 2xx dans les 10 secondes, avec le même identifiant ; ignorez les identifiants déjà acceptés, puis dédupliquez sur l'identifiant de message, car une modification que Meta renvoie est transférée de nouveau sous un nouvel identifiant.
  • Des accusés de réception lents. Répondez d'abord et traitez ensuite ; un gestionnaire qui attend le modèle expire, et le même événement revient.
  • Une personne au téléphone. Un événement smb_message_echoes signifie qu'un humain a répondu depuis l'application ; restez silencieux sur cette conversation pendant quelques heures.
  • Plusieurs workers. Les ensembles en mémoire ne couvrent pas plusieurs processus ; déplacez les stockages vers Redis ou votre base de données.
  • Deux répondeurs. Une automatisation de réponse IA et votre propre agent sur les mêmes conversations répondent tous deux, et vos envois via l'API Graph ne sont pas des échos, donc ils ne mettent pas les automatisations en pause. Choisissez un seul répondeur par numéro.

D'où viennent les secrets et identifiants ?

Du tableau de bord ou du connecteur MCP, et ils ne doivent figurer que dans l'environnement de votre serveur. get_api_credentials renvoie graph_api_base, waba_id, phone_number_id, send_endpoint et access_token, le token propre à l'entreprise ; la page du numéro affiche les mêmes valeurs sous « Brancher votre propre système ». Si access_token est null, reconnectez le numéro depuis un ordinateur avec « Reconnect » pour émettre un token. Traitez le token comme un mot de passe, car quiconque le détient peut envoyer des messages au nom de l'entreprise.

EC_FORWARD_SECRETShown once when you save a Forward URL, or returned once by set_inbound_mode; New secret rotates it
EC_AUTOMATION_SECRETSigning secret on the automation's page, under its Call my webhook step
SEND_ENDPOINT, WA_TOKENsend_endpoint and access_token from get_api_credentials
PATH_SECRET, VERIFY_TOKENDirect route: 32 or more random characters in the URL, and the handshake token you chose
AI_BASE_URL, AI_KEY, AI_MODELAny OpenAI-compatible API, such as https://api.openai.com/v1 or https://openrouter.ai/api/v1

Erreurs courantes

  • Vérifier la signature HMAC sur du JSON resérialisé. json.dumps de Python ajoute des espaces après les séparateurs par défaut, donc un corps analysé puis resérialisé ne correspond plus ; vérifiez les octets bruts.
  • Décoder le secret en base64 ou retirer son préfixe whsec_. La clé est la chaîne complète en texte UTF-8, exactement telle qu'elle vous a été montrée une seule fois.
  • Valider X-Hub-Signature-256 sur la route directe avec votre propre secret d'application Meta. Meta signe avec le secret d'application d'easyCoexistence, qui n'est pas partagé ; les vrais événements échouent alors. Authentifiez avec le secret du chemin.
  • Calculer la fenêtre à partir de l'heure d'arrivée. Un transfert réessayé plusieurs heures plus tard porte toujours l'horodatage original de Meta ; comparez à celui-ci, sinon l'agent répond après 24 heures et Meta refuse l'envoi.
Faire cela avec EasyCoexistence

Chaque numéro est surveillé 24 h/24, avec des alertes en cas de coupure de connexion. De US$ 9 à US$ 0,75 par numéro et par mois, en baissant à mesure que vous ajoutez des numéros, avec les 3 premiers jours en essai gratuit.

Questions fréquemment posées

L'agent peut-il comprendre les notes vocales et les photos ?

Oui, avec votre propre code. Le payload de Meta contient l'identifiant du média : téléchargez-le avec GET /<media-id> et le token du numéro, récupérez l'URL renvoyée avec le même en-tête Authorization, puis transcrivez-le ou décrivez-le avec votre modèle. Les automatisations ne voient que des espaces réservés comme [voice message].

Quels modèles les exemples peuvent-ils utiliser ?

Tout modèle derrière un endpoint de complétion de chat compatible OpenAI, y compris celui d'OpenAI et ceux accessibles via OpenRouter, ou remplacez askModel et ask_model par le SDK de votre fournisseur. easyCoexistence ne facture jamais l'IA : votre fournisseur vous facture directement.

L'agent peut-il démarrer une conversation ?

Seulement avec un template approuvé, envoyé avec type template au même endpoint d'envoi. Sur un numéro Coexistence, les templates ne partent que par l'API, jamais depuis l'application téléphonique, et Meta les facture par message au compte WhatsApp Business propre à l'entreprise.

Un seul agent peut-il servir plusieurs numéros ?

Oui. Routez selon value.metadata.phone_number_id ou connection.phone_number_id, et gardez un endpoint d'envoi, un token et un secret de transfert par numéro, car chaque numéro a les siens.

Poursuivre la lecture

Prêt à commencer ?

Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.

Commencer l'essai gratuit

Vérifié le