AccediInizia la prova gratuita
Meta Tech Provider

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.

5 min

Il gap massimo accettato tra la t della firma e il tuo orologio; ogni nuovo tentativo viene firmato di nuovo con una t nuova.

10 s

Quanto attende un POST inoltrato una risposta 2xx prima che easyCoexistence pianifichi un nuovo tentativo di quella consegna.

7 days

Quanto Meta riprova un webhook diretto che non ha ricevuto HTTP 200, cosa che può consegnare lo stesso messaggio due volte.

24 hours

Finestra di servizio clienti dopo l'ultimo messaggio dell'utente; fuori da essa Meta accetta solo messaggi template.

20 mps

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, 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

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: 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()}`);
}

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: 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);

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: 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

Come 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_echoes significa 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.

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

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.
Farlo con EasyCoexistence

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 gratuita

Verificato il