Prijavite seZapočnite besplatno probno razdoblje
Meta Tech Provider

Izradite WhatsApp AI agenta u Node.js i Pythonu na Coexistence broju

Poruke s broja primajte bilo proslijeđene uz HMAC potpis koji provjeravate (X-EC-Signature), bilo izravno s Metinog webhooka s tajnom u URL-u. Zatim preskočite poruku čiji je ID poruke već obrađen, ostanite tihi u razgovoru u kojem eho pokazuje da je osoba odgovorila s telefona, a odgovor modela šaljite kroz Cloud API samo unutar 24 sata od posljednje poruke kupca.

easyCoexistence povezuje broj koji poslovanje i dalje koristi u aplikaciji WhatsApp Business s Metinim Cloud API-jem, daje vašem kodu vjerodajnice preko get_api_credentials i usmjerava poruke izravno od Mete na vaš poslužitelj ili preko potpisanog proslijeđivanja uz uključene automatizacije.

5 min

Najveći razmak koji se prihvaća između t iz potpisa i vašeg sata; svaki ponovni pokušaj ponovno je potpisan novim t.

10 s

Koliko dugo proslijeđeni POST čeka 2xx prije nego easyCoexistence zakaže ponovni pokušaj te isporuke.

7 days

Koliko dugo Meta ponavlja izravni webhook koji nije dobio HTTP 200, što može dostaviti istu poruku dvaput.

24 hours

Prozor za korisničku podršku nakon posljednje poruke korisnika; izvan njega Meta prihvaća samo predloške.

20 mps

Fiksni protok broja koji se koristi i s aplikacijom WhatsApp Business i s Cloud API-jem.

Koju rutu treba koristiti kodirani agent?

Proslijeđivanje znači da broj ostaje u načinu s uključenim automatizacijama: Meta isporučuje easyCoexistenceu, automatizacije i dalje mogu raditi, a potpisana kopija svake Metine promjene ide na vaš URL za proslijeđivanje. Varijanta uopće ne treba proslijeđivanje: korak automatizacije Call my webhook šalje POST poruke na vaš endpoint i šalje sve što vratite kao {"reply"} unutar 20 sekundi, a deduplikacija, pauza za telefon i provjera 24-satnog prozora obavljaju se umjesto vas.

Izravno znači da Metin webhook šalje izravno na vaš endpoint, postavljen funkcijom set_webhook_destination, a easyCoexistence nikad ne vidi poruke. Automatizacije su za taj broj isključene, pa su sve zaštite vaše, kao i uvoz 6-mjesečne povijesti ako se odredište spremi unutar 24 sata od povezivanja. Primjeri niže obrađuju sva tri ulazna mjesta jednom zajedničkom jezgrom.

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

Što agent radi s porukom u Node.js-u?

agent.mjs sadrži logiku koju dijele obje rute. Bilježi vrijeme posljednje poruke kupca, povlači se na 4 sata u razgovoru kad događaj smb_message_echoes pokaže da je netko odgovorio iz aplikacije WhatsApp Business (zadano to koriste easyCoexistence automatizacije), preskače ID poruke koji je već obrađen i šalje samo unutar 24-satnog prozora. Prozor se mjeri prema vremenskoj oznaci same poruke, a ne prema trenutku kad je stigla do vas, jer ponovno poslana isporuka može doći i nakon nekoliko sati.

Korisnici se identificiraju prema BSUID-u (from_user_id, odnosno to_user_id kod eha) uz broj telefona kao rezervu, a korisnik poznat samo po BSUID-u dobiva odgovor s recipient umjesto to. Poziv modelu koristi bilo koji API za chat completions kompatibilan s OpenAI-jem; zamijenite ga SDK-om svog pružatelja ako želite.

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

Kako provjeravati i usmjeravati događaje u Node.js-u?

server.mjs izlaže tri ulazna mjesta. /ec/forward prima proslijeđivanja upravljanih brojeva: provjerava X-EC-Signature na neobrađenim bajtovima s tajnim ključem za proslijeđivanje broja, odgovara 200 prije ikakvog rada i preskače ID isporuke koji je već prihvatio, jer ponovni pokušaj nosi isti ID s novim potpisom. event u tijelu je Metino ime polja, a value je Metin change, nepromijenjen. /ec/agent odgovara na korak Call my webhook, potpisan vlastitim tajnim ključem za potpisivanje te automatizacije, i pretvara povijest u poteze razgovora. /meta/:secret je izravna ruta: odgovara na Metin GET handshake sirovim hub.challenge i prihvaća POST-ove samo na putanji s tajnom.

HMAC ključ je cijeli tajni niz, uključujući prefiks whsec_, kao UTF-8 tekst. express.raw čuva bajtove netaknutima, a njegova granica od 5 MB ostavlja prostora za Metine payloade do 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);

Kako isti agent izgleda u Pythonu?

Jedna Flask datoteka s istim trima rutama i istim pravilima. request.get_data() vraća neobrađeno tijelo za HMAC, hmac.compare_digest obavlja usporedbu u konstantnom vremenu, a posao se izvršava u pozadinskoj dretvi nakon 200, pa ni easyCoexistence ni Meta ne čekaju vaš model. Pokrenite ga naredbom flask --app agent run dok razvijate, a iza gunicorna ili drugog WSGI poslužitelja u produkciji.

Skup u memoriji i rječnici rade za jedan proces. S više radnika ili instanci premjestite ih u Redis ili bazu podataka, koristeći upis set-if-absent s istekom za ID-ove poruka, inače dva radnika mogu odgovoriti na istu poruku.

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

Kako izbjeći dvostruke odgovore?

Dupliciranja imaju šest čestih uzroka, a primjeri gore obrađuju prvih pet:

  • Metini ponovni pokušaji. Izravni webhook ponavlja se do 7 dana nakon svega osim HTTP 200; čuvajte spremište ID-ova poruka i preskačite ID-ove koji su već obrađeni.
  • Ponovni pokušaji proslijeđivanja. easyCoexistence ponavlja isporuku koja nije dobila 2xx unutar 10 sekundi, s istim ID-om; preskočite ID-ove koji su već prihvaćeni, zatim deduplicirajte prema ID-u poruke, jer promjenu koju Meta ponovno isporuči proslijeđuje se ponovno pod novim ID-om.
  • Spora potvrda. Prvo odgovorite, zatim radite; handler koji čeka na model istekne (timeout), a isti događaj se vraća.
  • Osoba na telefonu. Događaj smb_message_echoes znači da je netko odgovorio iz aplikacije; ostanite tihi u tom razgovoru nekoliko sati.
  • Više radnika. Skupovi u memoriji ne protežu se preko procesa; premjestite spremišta u Redis ili bazu podataka.
  • Dva odgovaratelja. Automatizacija AI odgovora i vaš vlastiti agent u istim razgovorima oboje odgovaraju, a vaša slanja preko Graph API-ja nisu ehoi, pa ne pauziraju automatizacije. Odaberite jednog odgovaratelja po broju.

Odakle dolaze tajne i vjerodajnice?

Iz nadzorne ploče ili MCP konektora, a pripadaju samo okruženju vašeg poslužitelja. get_api_credentials vraća graph_api_base, waba_id, phone_number_id, send_endpoint i access_token, vlastiti token poslovnog računa; stranica broja prikazuje iste vrijednosti pod naslovom Povežite vlastiti sustav. Ako je access_token null, ponovno povežite broj s računala pomoću Reconnect da izdate token. S tokenom postupajte kao s lozinkom, jer tko ga ima može slati poruke u ime tvrtke.

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

Uobičajene pogreške

  • Provjera HMAC-a na ponovno serijaliziranom JSON-u. Python-ov json.dumps po zadanom dodaje razmake nakon separatora, pa tijelo koje se parsira i ponovno ispiše više ne odgovara; provjeravajte neobrađene bajtove.
  • Dekodiranje tajne iz Base64 formata ili odbacivanje prefiksa whsec_. Ključ je cijeli niz kao UTF-8 tekst, točno kako vam je jednom prikazan.
  • Provjera X-Hub-Signature-256 na izravnoj ruti vlastitom tajnom Meta aplikacije. Meta potpisuje tajnom aplikacije easyCoexistence, koja nije dijeljena, pa autentični događaji ne prolaze; autentificirajte se tajnom u putanji.
  • Čitanje prozora iz vremena dolaska. Proslijeđivanje ponovno poslano nakon nekoliko sati i dalje nosi Metinu izvornu vremensku oznaku; usporedite s njom, inače agent odgovori nakon 24 sata i Meta odbije slanje.
Radite ovo uz EasyCoexistence

Svaki broj nadzire se 24/7, uz upozorenja kad veza padne. Od US$ 9 do US$ 0,75 po broju mjesečno, uz pad kako dodajete brojeve, a prva 3 dana su besplatna.

Često postavljana pitanja

Može li agent razumjeti glasovne poruke i fotografije?

Da, uz vlastiti kod. Metin payload nosi ID medija: preuzmite ga putem GET /<media-id> i tokenom broja, zatim dohvatite vraćeni URL s istim Authorization zaglavljem, pa transkribirajte ili opišite sadržaj vašim modelom. Automatizacije vide samo zamjenske oznake poput [voice message].

Koje modele uzorci mogu koristiti?

Bilo koji model iza endpointa za chat completions kompatibilnog s OpenAI-jem, uključujući OpenAI-jeve modele i one kojima se pristupa preko OpenRoutera, ili zamijenite askModel i ask_model SDK-om svog pružatelja. easyCoexistence nikad ne naplaćuje AI: pružatelj vam naplaćuje izravno.

Može li agent pokrenuti razgovor?

Samo s odobrenim predloškom, poslanim s type template na isti endpoint za slanje. Na Coexistence broju predlošci idu samo preko API-ja, nikad iz aplikacije na telefonu, a Meta ih naplaćuje po poruci na račun WhatsApp Business samog poslovanja.

Može li jedan agent služiti za više brojeva?

Da. Usmjeravajte prema value.metadata.phone_number_id ili connection.phone_number_id i čuvajte endpoint za slanje, token i tajni ključ za proslijeđivanje za svaki broj, jer svaki broj ima svoje.

Nastavite čitati

Spremni za početak?

Postavite WhatsApp Coexistence u nekoliko minuta, a ne mjeseci. Aplikacija i dalje radi na telefonu.

Započnite besplatno probno razdoblje

Provjereno na