Gumawa ng WhatsApp AI agent sa Node.js at Python sa Coexistence na numero
Tanggapin ang mga mensahe ng numero, alinman sa naka-forward na may HMAC signature na bine-verify ninyo (X-EC-Signature), o direkta mula sa webhook ng Meta na may secret sa URL. Pagkatapos, laktawan ang anumang ID ng mensahe na naproseso na, huwag sumagot sa chat kung saan may echo na nagpapakitang may taong sumagot mula sa telepono, at ipadala ang sagot ng inyong model sa pamamagitan ng Cloud API lamang sa loob ng 24 oras mula sa huling mensahe ng customer.
Ikinokonekta ng easyCoexistence ang numerong patuloy na ginagamit ng negosyo sa WhatsApp Business app sa Cloud API ng Meta, binibigyan ang code ninyo ng credentials nito sa pamamagitan ng get_api_credentials, at dinadala ang mga mensahe nang direkta mula sa Meta papunta sa server ninyo, o sa pamamagitan ng naka-sign na forward kapag naka-on ang automations.
Pinakamalaking agwat na tatanggapin sa pagitan ng t ng signature at ng orasan ninyo; bawat retry ay pinipirmahan muli na may bagong t.
Gaano katagal maghihintay ang naka-forward na POST para sa 2xx bago mag-iskedyul ng retry ang easyCoexistence para sa delivery na iyon.
Gaano katagal nire-retry ng Meta ang direktang webhook na hindi nakatanggap ng HTTP 200, na maaaring makapagpadala ng parehong mensahe nang dalawang beses.
Customer service window pagkatapos ng huling mensahe ng user; sa labas nito, template na mensahe lamang ang tinatanggap ng Meta.
Nakapirming throughput ng numerong ginagamit sa WhatsApp Business app at sa Cloud API.
Aling route ang dapat gamitin ng coded agent?
Ang naka-forward na route ay nangangahulugang nananatili ang numero sa Automations on mode: ipinapadala ng Meta ang lahat sa easyCoexistence, puwede pa ring tumakbo ang automations, at may naka-sign na kopya ng bawat Meta change na ipinapadala sa inyong Forward URL. May variant na walang forward: ang Call my webhook step ng isang automation ay nagpo-POST ng mensahe sa inyong endpoint at ipinapadala ang anumang {"reply"} na ibabalik ninyo sa loob ng 20 segundo, at ang dedupe, phone pause at 24-hour check ay ginagawa na para sa inyo.
Ang direct route ay nangangahulugang direktang nagpo-post ang webhook ng Meta sa inyong endpoint, na itinakda gamit ang set_webhook_destination, at hindi kailanman nakikita ng easyCoexistence ang mga mensahe. Naka-off ang automations para sa numerong iyon, kaya kayo ang may hawak ng lahat ng guard, pati na ang 6-month history import kapag na-save ang destination sa loob ng 24 oras mula sa pagkakakonekta. Ipinapakita ng mga sample sa ibaba ang tatlong entry point gamit ang iisang shared core.
| 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 |
Ano ang ginagawa ng agent sa isang mensahe, sa Node.js?
Hawak ng agent.mjs ang lohika na pinagsasaluhan ng dalawang route. Itinatala nito ang oras ng huling mensahe ng customer, humihinto nang 4 na oras sa isang chat kapag may smb_message_echoes event na nagpapakitang may sumagot mula sa WhatsApp Business app (ito ang default na ginagamit ng automations ng easyCoexistence), nilalaktawan ang ID ng mensaheng naproseso na, at nagpapadala lamang sa loob ng 24-oras na window. Sinusukat ang window mula sa sariling timestamp ng mensahe, hindi mula sa oras na dumating ito sa inyo, dahil maaaring dumating nang ilang oras nang huli ang na-retry na delivery.
Ang mga user ay kinikilala sa pamamagitan ng BSUID (from_user_id, o to_user_id sa echoes) na may numero ng telepono bilang fallback, at ang user na kilala lamang sa BSUID ay sinasagot gamit ang recipient sa halip na to. Ang tawag sa model ay gumagamit ng anumang OpenAI-compatible chat completions API; palitan ng SDK ng inyong provider kung mas gusto ninyo.
// 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()}`);
}Paano ninyo bine-verify at ini-route ang mga event sa Node.js?
Nagbibigay ang server.mjs ng tatlong entry point. Tinatanggap ng /ec/forward ang mga forward ng isang managed na numero: bine-verify nito ang X-EC-Signature sa raw bytes gamit ang forward secret ng numero, sumasagot ng 200 bago ang anumang gawain, at nilalaktawan ang delivery ID na tinanggap na, dahil ang retry ay may kaparehong ID na may bagong signature. Ang event sa body ay field name ng Meta at ang value ay ang change ng Meta, hindi binago. Sinasagot ng /ec/agent ang isang Call my webhook step, naka-sign gamit ang sariling Signing secret ng automation na iyon, at ginagawang chat turns ang history. Ang /meta/:secret ang direct route: sinasagot nito ang GET handshake ng Meta gamit ang raw hub.challenge at tumatanggap lamang ng POST sa secret path.
Ang HMAC key ay buong secret, kasama ang whsec_ prefix, bilang UTF-8 text. Pinananatiling buo ng express.raw ang bytes, at ang 5 MB limit nito ay nag-iiwan ng espasyo para sa Meta payload na hanggang 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);Paano ang itsura ng parehong agent sa Python?
Isang Flask file na may parehong tatlong route at parehong patakaran. Ibinabalik ng request.get_data() ang raw body para sa HMAC, ginagawa ng hmac.compare_digest ang constant-time na paghahambing, at tumatakbo ang gawain sa background thread pagkatapos ng 200, kaya hindi naghihintay sa model ninyo ang easyCoexistence o ang Meta. Patakbuhin ito gamit ang flask --app agent run habang nagde-develop, at sa likod ng gunicorn o ibang WSGI server sa production.
Ang in-memory set at mga dictionary ay angkop para sa iisang process. Kapag may ilang worker o instance, ilipat ang mga ito sa Redis o sa database ninyo, gamit ang set-if-absent write na may expiry para sa mga ID ng mensahe, kung hindi, magsasagot ang dalawang worker sa iisang mensahe.
# 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 "", 200Paano maiiwasan ang mga duplicate na sagot?
May anim na karaniwang sanhi ng duplicate, at tinutugunan ng mga sample sa itaas ang unang lima:
- Mga retry ng Meta. Nire-retry ang direktang webhook nang hanggang 7 araw pagkatapos ng anumang sagot maliban sa HTTP 200; panatilihin ang imbakan ng mga ID ng mensahe at laktawan ang mga ID na naproseso na.
- Mga retry ng forward. Nire-retry ng easyCoexistence ang delivery na walang natanggap na 2xx sa loob ng 10 segundo, na may kaparehong ID; laktawan ang mga ID na tinanggap na, saka mag-dedupe sa ID ng mensahe, dahil ang change na muling ipinadala ng Meta ay naka-forward ulit sa ilalim ng bagong ID.
- Mabagal na acknowledgement. Sumagot muna, saka gumawa; ang handler na naghihintay sa model ay mag-time out, at babalik ang kaparehong event.
- Taong nasa telepono. Ang
smb_message_echoesevent ay nangangahulugang may sumagot mula sa app; manatiling tahimik sa chat na iyon nang ilang oras. - Maraming worker. Hindi umaabot sa ibang process ang in-memory set; ilipat ang imbakan sa Redis o sa database ninyo.
- Dalawang sumasagot. Parehong sasagot sa iisang chat ang AI-reply automation at ang sariling agent ninyo, at ang mga send ninyo sa Graph API ay hindi echo, kaya hindi nila pinapatigil ang automations. Pumili ng isang sumasagot kada numero.
Saan nanggagaling ang mga secret at credential?
Mula sa dashboard o sa MCP connector, at dapat nasa environment lamang ng server ninyo ang mga ito. Ibinabalik ng get_api_credentials ang graph_api_base, waba_id, phone_number_id, send_endpoint at access_token, ang sariling token ng negosyo; ipinapakita ng pahina ng numero ang parehong value sa ilalim ng Plug in your own system. Kung null ang access_token, ikonekta muli ang numero mula sa computer gamit ang Reconnect para mag-issue ng token. Ituring ang token na parang password, dahil sinumang may hawak nito ay makakapagpadala ng mensahe bilang negosyo.
Mga karaniwang pagkakamali
- Pag-check ng HMAC sa muling na-serialize na JSON. Nagdaragdag ang json.dumps ng Python ng espasyo pagkatapos ng separator bilang default, kaya hindi na tutugma ang body na na-parse at na-dump muli; i-verify ang raw bytes.
- Pag-decode ng secret gamit ang Base64 o pag-alis ng whsec_ prefix nito. Ang key ay buong string bilang UTF-8 text, eksaktong katulad ng ipinakita sa inyo minsan lang.
- Pag-validate ng X-Hub-Signature-256 sa direct route gamit ang sarili ninyong Meta app secret. Pumipirma ang Meta gamit ang app secret ng easyCoexistence, na hindi ibinabahagi, kaya bumabagsak ang mga tunay na event; mag-authenticate gamit ang path secret.
- Pagbasa ng window mula sa oras ng pagdating. Ang forward na na-retry makalipas ang ilang oras ay may dala pa ring orihinal na timestamp ng Meta; ikumpara dito, kung hindi, sasagot ang agent pagkatapos ng 24 na oras at tatanggihan ng Meta ang pagpapadala.
Bawat numero ay ma-monitor 24/7, na may alerto kapag bumagsak ang koneksyon. US$ 9 hanggang US$ 0.75 kada numero kada buwan, bumababa habang dumarami ang numero, at libre ang unang 3 araw.
Mga madalas itanong
Kaya bang maintindihan ng agent ang voice note at larawan?
Oo, gamit ang sariling code ninyo. Naglalaman ang payload ng Meta ng media ID: i-download ito gamit ang GET /<media-id> at ang token ng numero, kunin ang ibinalik na URL gamit ang parehong Authorization header, at saka i-transcribe o ilarawan gamit ang model ninyo. Ang automations ay nakikita lamang ang mga placeholder tulad ng [voice message].
Anong model ang puwedeng gamitin ng mga sample?
Anumang model na nasa likod ng OpenAI-compatible chat completions endpoint, kasama ang sa OpenAI at ang mga naaabot sa pamamagitan ng OpenRouter, o palitan ang askModel at ask_model ng SDK ng inyong provider. Hindi kailanman naniningil ang easyCoexistence para sa AI: direktang sinisingil kayo ng provider ninyo.
Puwede bang magsimula ng usapan ang agent?
Oo, pero gamit lamang ang naaprubahang template, na ipinapadala na may type template sa parehong send endpoint. Sa Coexistence na numero, sa API lamang lumalabas ang template, hindi kailanman mula sa phone app, at sinisingil ito ng Meta kada mensahe sa sariling WhatsApp Business Account ng negosyo.
Kaya ba ng isang agent ang ilang numero?
Oo. I-route ayon sa value.metadata.phone_number_id o connection.phone_number_id, at magtakda ng send endpoint, token, at forward secret kada numero, dahil may kanya-kanyang sarili ang bawat numero.
Magpatuloy sa pagbabasa
Handa na po ba kayong magsimula?
I-set up ang WhatsApp Coexistence sa loob ng ilang minuto, hindi buwan. Patuloy na gumagana ang app sa telepono.
Magsimula ng Libreng TrialNa-verify noong