Napravite WhatsApp AI agenta u Node.js i Pythonu na Coexistence broju
Primate poruke broja ili prosleđene uz HMAC potpis koji proveravate (X-EC-Signature) ili direktno sa Meta webhooka, uz tajni ključ u URL-u. Zatim preskočite svaku poruku čiji je ID već obrađen, ostanite tihi u razgovoru u kom eho pokazuje da je osoba odgovorila sa telefona, i šaljite odgovor modela preko Cloud API-ja samo u roku od 24 sata od poslednje poruke kupca.
easyCoexistence povezuje broj koji firma i dalje koristi u WhatsApp Business aplikaciji sa Cloud API-jem, daje vašem kodu akreditive preko get_api_credentials i usmerava poruke direktno sa Meta-e na vaš server ili kroz potpisano prosleđivanje uz uključene automatizacije.
Najveći dozvoljeni razmak između t iz potpisa i vašeg sata; svaki ponovni pokušaj se potpisuje ponovo sa novim t.
Koliko prosleđeni POST čeka na 2xx pre nego što easyCoexistence zakaže ponovni pokušaj te isporuke.
Koliko Meta ponavlja direktni webhook koji nije dobio HTTP 200, što može dostaviti istu poruku dvaput.
Prozor za korisničku podršku posle poslednje poruke korisnika; van njega Meta prihvata samo poruke sa šablonom.
Fiksni propusni kapacitet broja koji se koristi i sa WhatsApp Business aplikacijom i sa Cloud API-jem.
Koji tok treba da koristi agent u kodu?
Prosleđivanje znači da broj ostaje u režimu Automatizacije: Meta isporučuje easyCoexistence-u, automatizacije i dalje mogu da rade, a potpisana kopija svake Meta promene ide na vaš URL za prosleđivanje. Postoji i varijanta bez prosleđivanja: korak automatizacije „Pozovi moj webhook“ šalje poruku na vaš endpoint i šalje sve što vratite u {"reply"} u roku od 20 sekundi, a deduplikacija, pauza za telefon i provera od 24 sata urade se umesto vas.
Direktno znači da Meta šalje sopstveni webhook pravo na vaš endpoint, podešen pomoću set_webhook_destination, i da easyCoexistence nikad ne vidi poruke. Automatizacije su za taj broj isključene, pa su sve zaštite vaše, kao i uvoz istorije od 6 meseci ako se odredište sačuva u roku od 24 sata od povezivanja. Primeri ispod obrađuju sva tri ulaza jednim zajedničkim jezgrom.
| 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 |
Šta agent radi sa porukom, u Node.js?
agent.mjs sadrži logiku koju dele oba toka. Beleži vreme poslednje poruke korisnika, pauzira na 4 sata u razgovoru kad smb_message_echoes događaj pokaže da je neko odgovorio iz WhatsApp Business aplikacije (podrazumevano koriste easyCoexistence automatizacije), preskače ID poruke koji je već obrađen i šalje samo unutar prozora od 24 sata. Prozor se meri od sopstvenog vremenskog žiga poruke, a ne od trenutka kad je stigla, jer ponovno poslata isporuka može stići satima kasnije.
Korisnici se označavaju BSUID-om (from_user_id, ili to_user_id na ehovima), a broj telefona je rezervna oznaka. Korisnik poznat samo po BSUID-u dobija odgovor preko polja recipient umesto to. Poziv modelu koristi bilo koji API kompatibilan sa OpenAI za chat completions; zamenite ga SDK-em vašeg provajdera ako želite.
// 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()}`);
}Kako se događaji proveravaju i usmeravaju u Node.js?
server.mjs izlaže tri ulaza. /ec/forward prima prosleđivanja za upravljane brojeve: proverava X-EC-Signature nad sirovim bajtovima pomoću tajnog ključa prosleđivanja za broj, odgovara sa 200 pre bilo kog rada i preskače ID isporuke koji je već prihvaćen, jer ponovni pokušaj nosi isti ID sa novim potpisom. Polje event sadrži Metin naziv polja, a polje value Metinu promenu, nepromenjenu. /ec/agent odgovara na korak Pozovi moj webhook, potpisan sopstvenim ključem potpisa te automatizacije, i pretvara istoriju u razgovorne poteze. /meta/:secret je direktna ruta: odgovara na Metin GET handshake sirovim hub.challenge i prihvata POST samo na putanji sa tajnom.
HMAC ključ je ceo tajni niz, uključujući prefiks whsec_, kao UTF-8 tekst. express.raw čuva bajtove netaknutim, a njegova granica od 5 MB ostavlja prostor za Meta payload do 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);Kako isti agent izgleda u Pythonu?
Jedan Flask fajl sa istim trima rutama i istim pravilima. request.get_data() vraća sirovo telo za HMAC, hmac.compare_digest obavlja poređenje konstantnog vremena, a posao se izvršava u pozadinskoj niti posle 200, tako da ni easyCoexistence ni Meta ne čekaju vaš model. Pokrenite ga sa flask --app agent run dok razvijate, a iza gunicorna ili drugog WSGI servera u produkciji.
Skup i rečnici u memoriji odgovaraju jednom procesu. Sa više radnih procesa ili instanci prebacite ih u Redis ili bazu, koristeći upis set-if-absent sa istekom za ID-jeve poruka, inače dva radnika mogu odgovoriti na istu poruku.
# 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 "", 200Kako se izbegavaju duplikati odgovora?
Duplikati imaju šest čestih uzroka, a primeri iznad rešavaju prvih pet:
- Meta-ini ponovni pokušaji. Direktni webhook se ponavlja do 7 dana posle svega osim HTTP 200; čuvajte skup ID-jeva poruka i preskačite one koji su već obrađeni.
- Ponovni pokušaji prosleđivanja. easyCoexistence ponavlja isporuku koja nije dobila 2xx za 10 sekundi, sa istim ID-jem; preskočite ID-jeve koji su već prihvaćeni, pa uklanjajte duplikate po ID-ju poruke, jer se promena koju Meta ponovo isporuči prosleđuje ponovo pod novim ID-jem.
- Spori potvrdni odgovori. Prvo odgovorite, pa radite posle; rukovalac koji čeka model istekne, a isti događaj se vraća.
- Osoba na telefonu. Događaj
smb_message_echoesznači da je neko odgovorio iz aplikacije; ostanite tihi u tom razgovoru nekoliko sati. - Više radnika. Skupovi u memoriji ne prelaze granice procesa; prebacite skladišta u Redis ili bazu.
- Dva odgovarača. Automatizacija AI odgovora i vaš agent u istim razgovorima oba odgovaraju, a vaša slanja preko Graph API-ja nisu eho, pa ne pauziraju automatizacije. Izaberite jednog odgovarača po broju.
Odakle dolaze tajne i akreditivi?
Iz kontrolne table ili MCP konektora, i pripadaju samo okruženju vašeg servera. get_api_credentials vraća graph_api_base, waba_id, phone_number_id, send_endpoint i access_token, sopstveni token firme; stranica broja prikazuje iste vrednosti pod „Povežite svoj sistem“. Ako je access_token null, ponovo povežite broj sa računara dugmetom Reconnect da biste izdali token. Čuvajte token kao lozinku, jer ko god ga ima može da šalje poruke u ime firme.
Česte greške
- Provera HMAC-a nad ponovo serijalizovanim JSON-om. Pythonov json.dumps podrazumevano dodaje razmake posle separatora, pa telo koje je parsirano i ponovo serijalizovano više ne odgovara; proveravajte sirove bajtove.
- Dekodiranje tajne iz base64 ili brisanje prefiksa whsec_. Ključ je ceo niz kao UTF-8 tekst, tačno onako kako vam je jednom prikazan.
- Provera X-Hub-Signature-256 na direktnoj ruti sa sopstvenim tajnim ključem Meta aplikacije. Meta potpisuje tajnim ključem aplikacije easyCoexistence, koji nije podeljen, pa pravi događaji ne prolaze; autentifikujte se tajnom iz putanje.
- Računanje prozora od vremena dolaska. Prosleđena poruka koja se ponovo šalje posle satima i dalje nosi Metin originalni vremenski žig; poredite sa njim, inače agent odgovara posle 24 sata i Meta odbija slanje.
Svaki broj se prati 24/7, uz upozorenja kad veza padne. Od US$ 9 do US$ 0.75 po povezanom broju mesečno, pada kako dodajete brojeve, uz besplatni probni period od 3 dana.
Često postavljana pitanja
Može li agent da razume glasovne poruke i fotografije?
Da, uz vaš sopstveni kod. Metin payload nosi ID medija: preuzmite ga pomoću GET /<media-id> i tokena broja, zatim preuzmite vraćeni URL sa istim Authorization zaglavljem, pa transkribujte ili opišite sadržaj vašim modelom. Automatizacije vide samo zamenske oznake poput [voice message].
Koje modele mogu da koriste primeri?
Bilo koji model iza OpenAI-kompatibilnog endpointa za chat completions, uključujući modele od OpenAI-ja i one dostupne preko OpenRouter-a, ili zamenite askModel i ask_model SDK-em vašeg provajdera. easyCoexistence nikad ne naplaćuje AI: provajder vam naplaćuje direktno.
Može li agent da započne razgovor?
Samo sa odobrenim šablonom, poslatim sa type template na isti endpoint za slanje. Na Coexistence broju šabloni idu samo preko API-ja, nikad iz aplikacije na telefonu, a Meta ih naplaćuje po poruci firmi, na njen sopstveni WhatsApp Business nalog.
Da li jedan agent opslužuje više brojeva?
Da. Usmeravajte po value.metadata.phone_number_id ili connection.phone_number_id, i držite endpoint za slanje, token i tajni ključ prosleđivanja za svaki broj, jer svaki broj ima sopstvene.
Nastavite sa čitanjem
Spremni da počnete?
Podesite WhatsApp Coexistence za nekoliko minuta, a ne meseci. Aplikacija nastavlja da radi na telefonu.
Započnite besplatni probni periodProvereno na