Conectați-văÎncepeți perioada de probă gratuită
Meta Tech Provider

Creați un agent AI WhatsApp în Node.js și Python pe un număr Coexistence

Primiți mesajele numărului fie redirecționate, cu o semnătură HMAC pe care o verificați (X-EC-Signature), fie direct de la webhook-ul Meta, cu un secret în URL. Apoi ignorați orice id de mesaj deja tratat, rămâneți tăcut pe o conversație în care un eveniment echo arată că o persoană a răspuns de pe telefon și trimiteți răspunsul modelului prin Cloud API doar în 24 de ore de la ultimul mesaj al clientului.

easyCoexistence conectează numărul pe care firma îl folosește deja în aplicația WhatsApp Business la Cloud API de la Meta, oferă codului dumneavoastră credențialele prin get_api_credentials și direcționează mesajele direct de la Meta către serverul dumneavoastră sau printr-o redirecționare semnată, cu automatizările active.

5 min

Cel mai mare decalaj acceptat între t din semnătură și ceasul dumneavoastră; fiecare reîncercare este semnată din nou, cu un t nou.

10 s

Cât timp așteaptă un POST redirecționat un răspuns 2xx înainte ca easyCoexistence să programeze o reîncercare a livrării.

7 days

Cât timp reîncearcă Meta un webhook direct care nu a primit HTTP 200, lucru care poate livra același mesaj de două ori.

24 hours

Fereastra de serviciu pentru clienți după ultimul mesaj al utilizatorului; în afara ei, Meta acceptă doar mesaje șablon.

20 mps

Debitul fix al unui număr folosit atât cu aplicația WhatsApp Business, cât și cu Cloud API.

Ce rută ar trebui să folosească un agent scris în cod?

Redirecționarea înseamnă că numărul rămâne în modul „Automations”: Meta livrează către easyCoexistence, automatizările pot rula în continuare, iar o copie semnată a fiecărei modificări Meta ajunge la URL-ul de redirecționare. O variantă nu necesită deloc redirecționare: pasul „Call my webhook” al unei automatizări trimite mesajul la endpoint-ul dumneavoastră și trimite orice {"reply"} returnat în 20 de secunde, iar deduplicarea, pauza la telefon și verificarea ferestrei de 24 de ore sunt făcute pentru dumneavoastră.

Livrarea directă înseamnă că Meta trimite propriul webhook direct către endpoint-ul dumneavoastră, setat cu set_webhook_destination, iar easyCoexistence nu vede niciodată mesajele. Automatizările sunt dezactivate pentru acel număr, deci fiecare verificare vă aparține, la fel și importul istoricului de 6 luni, când destinația este salvată în 24 de ore de la conectare. Exemplele de mai jos tratează toate cele trei puncte de intrare cu un singur nucleu comun.

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

Ce face agentul cu un mesaj, în Node.js?

agent.mjs conține logica pe care o folosesc ambele rute. Înregistrează momentul ultimului mesaj al clientului, se retrage 4 ore dintr-o conversație când un eveniment smb_message_echoes arată că cineva a răspuns din aplicația WhatsApp Business (comportamentul implicit al automatizărilor easyCoexistence), sare peste un id de mesaj deja tratat și trimite doar în fereastra de 24 de ore. Fereastra se măsoară din marca de timp a mesajului însuși, nu din momentul în care a ajuns la dumneavoastră, deoarece o livrare reîncercată poate sosi cu ore întârziere.

Utilizatorii sunt identificați prin BSUID (from_user_id, sau to_user_id la echo-uri), cu numărul de telefon ca rezervă, iar un utilizator cunoscut doar prin BSUID primește răspuns cu recipient în loc de to. Apelul modelului folosește orice API de chat completions compatibil cu OpenAI; înlocuiți-l cu SDK-ul furnizorului dumneavoastră dacă preferați.

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

Cum verificați și rutați evenimentele în Node.js?

server.mjs expune cele trei puncte de intrare. /ec/forward primește redirecționările numerelor gestionate: verifică X-EC-Signature pe octeții brute, cu secretul de redirecționare al numărului, răspunde 200 înainte de orice prelucrare și sare peste un id de livrare deja acceptat, deoarece o reîncercare poartă același id cu o semnătură nouă. Câmpul event din corp este numele câmpului Meta, iar value este modificarea Meta, nemodificată. /ec/agent răspunde unui pas Call my webhook, semnat cu propriul secret de semnare al automatizării, și transformă istoricul în replici de chat. /meta/:secret este ruta directă: răspunde confirmării GET a Meta cu hub.challenge brut și acceptă POST-uri doar pe calea cu secret.

Cheia HMAC este secretul întreg, cu prefixul whsec_ inclus, ca text UTF-8. express.raw păstrează octeții intacți, iar limita de 5 MB lasă loc pentru payload-urile Meta de până la 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);

Cum arată același agent în Python?

Un singur fișier Flask cu aceleași trei rute și aceleași reguli. request.get_data() returnează corpul brut pentru HMAC, hmac.compare_digest face comparația în timp constant, iar lucrul se execută pe un fir de fundal după răspunsul 200, astfel încât nici easyCoexistence, nici Meta nu așteaptă modelul dumneavoastră. Rulați-l cu flask --app agent run în timpul dezvoltării și în spatele gunicorn sau al altui server WSGI în producție.

Setul și dicționarele din memorie sunt potrivite pentru un singur proces. Cu mai mulți workeri sau instanțe, mutați-le în Redis sau în baza de date, folosind o scriere set-if-absent cu expirare pentru id-urile de mesaj, altfel doi workeri vor răspunde la același mesaj.

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

Cum evitați răspunsurile duplicate?

Duplicatele au șase cauze frecvente, iar exemplele de mai sus tratează primele cinci:

  • Reîncercările Meta. Un webhook direct este reîncercat timp de până la 7 zile după orice altceva decât HTTP 200; păstrați un depozit de id-uri de mesaj și săriți peste id-urile deja tratate.
  • Reîncercările redirecționării. easyCoexistence reîncearcă o livrare care nu a primit 2xx în 10 secunde, cu același id; săriți peste id-urile deja acceptate, apoi deduplicați pe id-ul mesajului, deoarece o modificare redistribuită de Meta este redirecționată din nou sub un id nou.
  • Confirmări lente. Răspundeți mai întâi și lucrați apoi; un handler care așteaptă modelul expiră, iar același eveniment revine.
  • O persoană la telefon. Un eveniment smb_message_echoes înseamnă că cineva a răspuns din aplicație; rămâneți tăcut pe conversația respectivă câteva ore.
  • Mai mulți workeri. Seturile din memorie nu se extind pe mai multe procese; mutați depozitele în Redis sau în baza de date.
  • Doi responderi. O automatizare de răspuns AI și agentul dumneavoastră pe aceleași conversații răspund amândouă, iar trimiterile prin Graph API nu sunt echo-uri, deci nu opresc automatizările. Alegeți un singur responder pe număr.

De unde vin secretele și credențialele?

Din dashboard-ul sau din conectorul MCP, și aparțin doar mediului serverului dumneavoastră. get_api_credentials returnează graph_api_base, waba_id, phone_number_id, send_endpoint și access_token, token-ul propriu al firmei; pagina numărului arată aceleași valori sub „Plug in your own system”. Dacă access_token este null, reconectați numărul de pe un calculator, cu „Reconnect”, pentru a emite un token nou. Tratați token-ul ca pe o parolă, pentru că oricine îl deține poate trimite mesaje în numele firmei.

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

Greșeli frecvente

  • Verificarea HMAC pe JSON re-serializat. json.dumps din Python adaugă spații după separatori implicit, deci un corp parsat și apoi serializat din nou nu mai corespunde; verificați octeții brute.
  • Decodarea base64 a secretului sau eliminarea prefixului whsec_. Cheia este întregul șir ca text UTF-8, exact cum v-a fost arătat o singură dată.
  • Validarea X-Hub-Signature-256 pe ruta directă cu propriul secret al aplicației Meta. Meta semnează cu secretul aplicației easyCoexistence, care nu este distribuit, deci evenimentele autentice eșuează; autentificați cu secretul din cale.
  • Citirea ferestrei din momentul sosirii. O redirecționare reîncercată după ore poartă tot marca de timp originală a Meta; comparați cu aceasta, altfel agentul răspunde după 24 de ore, iar Meta refuză trimiterea.
Faceți acest lucru cu EasyCoexistence

Fiecare număr este monitorizat 24/7, cu alerte când o conexiune cade. De la US$ 9 până la US$ 0.75 per număr pe lună, scăzând pe măsură ce adăugați numere, cu primele 3 zile gratuite.

Întrebări frecvente

Poate agentul să înțeleagă mesaje vocale și fotografii?

Da, cu propriul dumneavoastră cod. Payload-ul Meta conține id-ul media: descărcați-l cu GET /<media-id> și token-ul numărului, aduceți URL-ul returnat cu același antet Authorization, apoi transcrieți sau descrieți conținutul cu modelul dumneavoastră. Automatizările văd doar substituenți precum [voice message].

Ce modele pot folosi exemplele?

Orice model din spatele unui endpoint de chat completions compatibil cu OpenAI, inclusiv cele ale OpenAI și cele accesate prin OpenRouter, sau înlocuiți askModel și ask_model cu SDK-ul furnizorului dumneavoastră. easyCoexistence nu facturează niciodată pentru AI: furnizorul dumneavoastră vă facturează direct.

Poate agentul să inițieze o conversație?

Doar cu un șablon aprobat, trimis cu type template la același endpoint de trimitere. Pe un număr Coexistence, șabloanele pleacă doar prin API, niciodată din aplicația de telefon, iar Meta le facturează per mesaj în contul WhatsApp Business Account al firmei.

Un singur agent servește mai multe numere?

Da. Rutați după value.metadata.phone_number_id sau connection.phone_number_id și păstrați un send endpoint, un token și un secret de redirecționare pentru fiecare număr, deoarece fiecare număr are propriile sale.

Continuați să citiți

Gata să începeți?

Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.

Începeți perioada de probă gratuită

Verificat la