Costruisci un agente AI per WhatsApp in Node.js e Python su un numero Coexistence
Ricevi i messaggi del numero, inoltrati con una firma HMAC da verificare (X-EC-Signature), oppure direttamente dal webhook di Meta con un segreto nell'URL. Poi salta ogni id di messaggio già gestito, resta in silenzio sulla chat dove un echo mostra che una persona ha risposto dal telefono, e invia la risposta del tuo modello tramite la Cloud API solo entro 24 ore dall'ultimo messaggio del cliente.
easyCoexistence collega il numero che l'azienda continua a usare nell'app WhatsApp Business alla Cloud API di Meta, fornisce al tuo codice le credenziali tramite get_api_credentials, e instrada i messaggi direttamente da Meta al tuo server oppure tramite un inoltro firmato con le automazioni attive.
Il gap massimo accettato tra la t della firma e il tuo orologio; ogni nuovo tentativo viene firmato di nuovo con una t nuova.
Quanto attende un POST inoltrato una risposta 2xx prima che easyCoexistence pianifichi un nuovo tentativo di quella consegna.
Quanto Meta riprova un webhook diretto che non ha ricevuto HTTP 200, cosa che può consegnare lo stesso messaggio due volte.
Finestra di servizio clienti dopo l'ultimo messaggio dell'utente; fuori da essa Meta accetta solo messaggi template.
Throughput fisso di un numero usato sia con l'app WhatsApp Business sia con la Cloud API.
Quale percorso deve usare un agente programmato?
Con l'inoltro il numero resta in Automazioni in modalità on: Meta consegna a easyCoexistence, le automazioni possono comunque girare e una copia firmata di ogni modifica di Meta va al tuo URL di inoltro. Una variante non richiede alcun inoltro: il passo Chiama il mio webhook di un'automazione invia il messaggio al tuo endpoint e invia qualsiasi {"reply"} tu restituisca entro 20 secondi, con deduplica, pausa del telefono e controllo delle 24 ore già fatti per te.
Diretto significa che Meta invia il proprio webhook direttamente al tuo endpoint, impostato con set_webhook_destination, e easyCoexistence non vede mai i messaggi. Le automazioni sono disattivate per quel numero, quindi ogni controllo è tuo, così come l'importazione dello storico di 6 mesi quando la destinazione viene salvata entro 24 ore dalla connessione. Gli esempi sotto gestiscono tutti e tre i punti di ingresso con un unico nucleo condiviso.
| Forwarded, signed | Direct from Meta | |
|---|---|---|
| Number mode | Automations on (managed) | Direct to your server |
| Body | One Meta change: id, event, received_at, connection, value | Meta's envelope: object, entry, changes |
| Authentication | X-EC-Signature, HMAC-SHA256 with a per-number secret | A secret in the URL path |
| Acknowledge | Any 2xx within 10 seconds | HTTP 200; Meta retries other codes |
| Retries | 7 attempts over about 33 hours | Up to 7 days |
| Reply | Graph API, or {"reply"} to a Call my webhook step | Graph API |
| History import | Not requested | Requested if saved within 24 hours of connecting |
Cosa fa l'agente con un messaggio, in Node.js?
agent.mjs contiene la logica che condividono entrambi i percorsi. Registra l'ora dell'ultimo messaggio del cliente, si mette in pausa per 4 ore su una chat quando un evento smb_message_echoes mostra che qualcuno ha risposto dall'app WhatsApp Business (quella predefinita usata dalle automazioni di easyCoexistence), salta un id di messaggio già gestito e invia solo entro la finestra di 24 ore. La finestra si misura dal timestamp del messaggio stesso, non da quando ti è arrivato, perché una consegna ritentata può arrivare con ore di ritardo.
Gli utenti sono identificati tramite BSUID (from_user_id, o to_user_id sugli echo) con il numero di telefono come riserva, e un utente noto solo tramite BSUID riceve la risposta con recipient invece di to. La chiamata al modello usa qualsiasi API di chat completions compatibile con OpenAI; sostituisci con l'SDK del tuo provider se preferisci.
// 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()}`);
}Come verifichi e instradi gli eventi in Node.js?
server.mjs espone i tre punti di ingresso. /ec/forward riceve gli inoltri dei numeri gestiti: verifica X-EC-Signature sui byte grezzi con il segreto di inoltro del numero, risponde 200 prima di qualsiasi elaborazione e salta un id di consegna già accettato, perché un nuovo tentativo porta lo stesso id con una firma nuova. Il campo event del corpo è il nome del campo di Meta e value è il change di Meta, invariato. /ec/agent risponde a un passo Chiama il mio webhook, firmato con il Signing secret di quella automazione, e trasforma lo storico in turni di chat. /meta/:secret è il percorso diretto: risponde all'handshake GET di Meta con l'hub.challenge grezzo e accetta POST solo sul percorso con il segreto.
La chiave HMAC è l'intero segreto, prefisso whsec_ incluso, come testo UTF-8. express.raw mantiene intatti i byte, e il suo limite di 5 MB lascia spazio per payload Meta fino a 3 MB.
// 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);Come si presenta lo stesso agente in Python?
Un unico file Flask con le stesse tre rotte e le stesse regole. request.get_data() restituisce il corpo grezzo per l'HMAC, hmac.compare_digest esegue il confronto a tempo costante, e il lavoro gira su un thread in background dopo il 200, così né easyCoexistence né Meta aspettano il tuo modello. Eseguilo con flask --app agent run durante lo sviluppo e dietro gunicorn o un altro server WSGI in produzione.
L'insieme e i dizionari in memoria vanno bene per un singolo processo. Con più worker o istanze, spostali su Redis o sul tuo database, usando una scrittura set-if-absent con scadenza per gli id dei messaggi, altrimenti due worker risponderanno allo stesso messaggio.
# 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 "", 200Come eviti le risposte duplicate?
I duplicati hanno sei cause comuni, e gli esempi sopra ne gestiscono le prime cinque:
- I tentativi di Meta. Un webhook diretto viene ritentato per fino a 7 giorni dopo qualsiasi risposta diversa da HTTP 200; conserva un archivio di id di messaggio e salta gli id già gestiti.
- I tentativi dell'inoltro. easyCoexistence ritenta una consegna che non ha ricevuto alcun 2xx entro 10 secondi, con lo stesso id; salta gli id già accettati, poi deduplica sull'id del messaggio, perché una modifica che Meta ri-consegna viene inoltrata di nuovo con un nuovo id.
- Conferme lente. Rispondi per prima cosa e lavora dopo; un handler che attende il modello va in timeout e lo stesso evento torna indietro.
- Una persona sul telefono. Un evento
smb_message_echoessignifica che qualcuno ha risposto dall'app; resta in silenzio su quella chat per alcune ore. - Più worker. Gli insiemi in memoria non si estendono tra processi; sposta gli archivi su Redis o sul tuo database.
- Due risponditori. Una automazione di risposta AI e il tuo agente sulle stesse chat rispondono entrambi, e i tuoi invii via Graph API non sono echo, quindi non mettono in pausa le automazioni. Scegli un solo risponditore per numero.
Da dove arrivano i segreti e le credenziali?
Dalla dashboard o dal connettore MCP, e devono stare solo nell'ambiente del tuo server. get_api_credentials restituisce graph_api_base, waba_id, phone_number_id, send_endpoint e access_token, il token dell'azienda; la pagina del numero mostra gli stessi valori sotto Collega il tuo sistema. Se access_token è null, ricollega il numero da un computer con Riconnetti per generare un token. Trattalo come una password, perché chiunque lo possieda può scrivere a nome dell'azienda.
Errori comuni
- Verificare l'HMAC su JSON riserializzato. json.dumps di Python aggiunge spazi dopo i separatori per impostazione predefinita, quindi un corpo letto e riscritto non corrisponde più; verifica i byte grezzi.
- Decodificare in base64 il segreto o togliere il prefisso whsec_. La chiave è l'intera stringa come testo UTF-8, esattamente come ti è stata mostrata una volta.
- Validare X-Hub-Signature-256 sul percorso diretto con la tua app secret di Meta. Meta firma con l'app secret di easyCoexistence, che non è condivisa, quindi gli eventi genuini falliscono; autentica con il segreto nel percorso.
- Leggere la finestra dall'ora di arrivo. Un inoltro ritentato dopo ore porta ancora il timestamp originale di Meta; confronta con quello, altrimenti l'agente risponde dopo 24 ore e Meta rifiuta l'invio.
Ogni numero è monitorato 24/7, con avvisi quando una connessione si interrompe. Da US$ 9 fino a US$ 0,75 per numero al mese, scendendo man mano che aggiungi numeri, con i primi 3 giorni di prova gratuita.
Domande frequenti
L'agente può capire note vocali e foto?
Sì, con il tuo codice. Il payload di Meta contiene l'id del media: scaricalo con GET /<media-id> e il token del numero, recupera l'URL restituito con lo stesso header Authorization, poi trascrivi o descrivi il contenuto con il tuo modello. Le automazioni vedono solo segnaposto come [voice message].
Quali modelli possono usare gli esempi?
Qualsiasi modello dietro un endpoint di chat completions compatibile con OpenAI, inclusi quello di OpenAI e quelli raggiunti tramite OpenRouter, oppure sostituisci askModel e ask_model con l'SDK del tuo provider. easyCoexistence non addebita mai l'AI: il tuo provider ti fattura direttamente.
L'agente può avviare una conversazione?
Solo con un template approvato, inviato con type template allo stesso send endpoint. Su un numero Coexistence i template partono solo tramite API, mai dall'app del telefono, e Meta li fattura per messaggio all'account WhatsApp Business dell'azienda.
Un solo agente può servire più numeri?
Sì. Instrada per value.metadata.phone_number_id o connection.phone_number_id, e mantieni un send endpoint, un token e un segreto di inoltro per ogni numero, perché ognuno ha il proprio.
Continua a leggere
Pronto per iniziare?
Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.
Inizia la prova gratuitaVerificato il