Bina ejen AI WhatsApp dalam Node.js dan Python pada nombor Coexistence
Terima mesej bagi nombor itu sama ada dimajukan dengan tandatangan HMAC yang anda sahkan (X-EC-Signature) atau terus dari webhook Meta dengan rahsia dalam URL. Kemudian langkau mana-mana id mesej yang telah dikendalikan, kekal senyap pada sembang yang menunjukkan gema daripada orang yang membalas dari telefon, dan hantar jawapan model anda melalui Cloud API hanya dalam tempoh 24 jam dari mesej terakhir pelanggan.
easyCoexistence menyambungkan nombor yang terus digunakan perniagaan dalam aplikasi WhatsApp Business kepada Cloud API Meta, memberikan kod anda kelayakannya melalui get_api_credentials, dan menghala mesej terus dari Meta ke pelayan anda atau melalui pemajuan bertandatangan dengan automasi dihidupkan.
Jurang terbesar yang diterima antara t tandatangan dengan jam anda; setiap cubaan semula ditandatangani semula dengan t yang baharu.
Berapa lama permintaan POST yang dimajukan menunggu respons 2xx sebelum easyCoexistence menjadualkan cubaan semula penghantaran itu.
Berapa lama Meta mencuba semula webhook terus yang tidak menerima HTTP 200, yang boleh menghantar mesej yang sama dua kali.
Tetingkap khidmat pelanggan selepas mesej terakhir pengguna; di luar tetingkap itu, Meta hanya menerima mesej templat.
Throughput tetap bagi nombor yang digunakan dengan kedua-dua aplikasi WhatsApp Business dan Cloud API.
Laluan mana patut digunakan oleh ejen berkod?
Dimajukan bermaksud nombor kekal dalam Automasi pada mod hidup: Meta menghantar kepada easyCoexistence, automasi masih boleh berjalan, dan salinan bertandatangan bagi setiap perubahan Meta dihantar ke URL Pemajuan anda. Varian tidak memerlukan pemajuan: langkah Call my webhook dalam automasi menghantar POST mesej ke endpoint anda dan menghantar apa sahaja {"reply"} yang anda pulangkan dalam masa 20 saat, dengan pendua, jeda telefon dan semakan 24 jam dilakukan untuk anda.
Terus bermaksud Meta menghantar webhook sendiri terus ke endpoint anda, ditetapkan dengan set_webhook_destination, dan easyCoexistence tidak sekali-kali melihat mesej. Automasi dimatikan bagi nombor itu, jadi semua pengawal menjadi tanggungjawab anda, begitu juga import sejarah 6 bulan apabila destinasi disimpan dalam masa 24 jam selepas menyambung. Sampel di bawah mengendalikan ketiga-tiga titik masuk dengan satu teras yang dikongsi.
| 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 |
Apa yang dilakukan ejen dengan mesej, dalam Node.js?
agent.mjs mengandungi logik yang dikongsi oleh kedua-dua laluan. Ia merekod masa mesej terakhir pelanggan, berundur selama 4 jam pada sembang apabila acara smb_message_echoes menunjukkan seseorang menjawab dari aplikasi WhatsApp Business (lalai yang digunakan oleh automasi easyCoexistence), melangkau id mesej yang telah dikendalikan, dan hanya menghantar dalam tetingkap 24 jam. Tetingkap diukur dari cap masa mesej itu sendiri, bukan dari masa ia sampai kepada anda, kerana penghantaran yang dicuba semula boleh tiba berjam-jam lewat.
Pengguna dikenal pasti melalui BSUID (from_user_id, atau to_user_id pada gema) dengan nombor telefon sebagai sandaran, dan pengguna yang hanya dikenali melalui BSUID dijawab menggunakan recipient, bukan to. Panggilan model menggunakan mana-mana API chat completions yang serasi dengan OpenAI; tukar kepada SDK pembekal anda jika anda mahu.
// 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()}`);
}Bagaimana anda mengesahkan dan menghala acara dalam Node.js?
server.mjs mendedahkan tiga titik masuk. /ec/forward menerima pemajuan bagi nombor terurus: ia mengesahkan X-EC-Signature pada bait mentah dengan rahsia pemajuan nombor itu, membalas 200 sebelum sebarang kerja, dan melangkau id penghantaran yang telah diterima, kerana cubaan semula membawa id yang sama dengan tandatangan baharu. Medan event dalam badan ialah nama medan Meta dan value ialah change Meta, tanpa diubah. /ec/agent membalas langkah Call my webhook, ditandatangani dengan rahsia penandatanganan automasi itu sendiri, dan menukar sejarah kepada giliran sembang. /meta/:secret ialah laluan terus: ia membalas handshake GET Meta dengan hub.challenge mentah dan hanya menerima POST pada laluan rahsia.
Kunci HMAC ialah keseluruhan rahsia, termasuk awalan whsec_, sebagai teks UTF-8. express.raw mengekalkan bait dalam keadaan utuh, dan had 5 MB memberi ruang untuk muatan Meta sehingga 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);Bagaimana kod Python ejen ini kelihatan?
Satu fail Flask dengan tiga laluan yang sama dan peraturan yang sama. request.get_data() memulangkan badan mentah untuk HMAC, hmac.compare_digest melakukan perbandingan masa-malar, dan kerja dijalankan pada benang latar belakang selepas 200, supaya tiada daripada easyCoexistence mahupun Meta menunggu model anda. Jalankan dengan flask --app agent run semasa membangun dan di belakang gunicorn atau pelayan WSGI lain dalam pengeluaran.
Set dan kamus dalam memori sesuai untuk satu proses. Dengan beberapa worker atau instans, pindahkan ke Redis atau pangkalan data anda, menggunakan tulisan set-if-absent dengan tempoh luput untuk id mesej, atau dua worker akan menjawab mesej yang sama.
# 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 "", 200Bagaimana anda mengelak balasan pendua?
Pendua mempunyai enam punca lazim, dan sampel di atas mengendalikan lima yang pertama:
- Cubaan semula Meta. Webhook terus dicuba semula sehingga 7 hari selepas apa sahaja selain HTTP 200; simpan stor id mesej dan langkau id yang telah dikendalikan.
- Cubaan semula pemajuan. easyCoexistence mencuba semula penghantaran yang tidak menerima 2xx dalam masa 10 saat, dengan id yang sama; langkau id yang telah diterima, kemudian lakukan penyahduaan pada id mesej, kerana perubahan yang dihantar semula oleh Meta dimajukan lagi di bawah id baharu.
- Pengakuan lewat. Balas dahulu dan kerjakan kemudian; pengendali yang menunggu model akan tamat masa, dan acara yang sama akan kembali.
- Orang di telefon. Acara
smb_message_echoesbermaksud seseorang menjawab dari aplikasi; kekal senyap pada sembang itu selama beberapa jam. - Beberapa worker. Set dalam memori tidak merentasi proses; pindahkan stor ke Redis atau pangkalan data anda.
- Dua penjawab. Automasi balasan AI dan ejen anda sendiri pada sembang yang sama kedua-duanya menjawab, dan penghantaran Graph API anda bukan gema, jadi ia tidak menjeda automasi. Pilih satu penjawab bagi setiap nombor.
Dari mana datangnya rahsia dan bukti kelayakan?
Dari dashboard atau penyambung MCP, dan ia hanya patut berada dalam persekitaran pelayan anda. get_api_credentials memulangkan graph_api_base, waba_id, phone_number_id, send_endpoint dan access_token, token milik perniagaan itu sendiri; halaman nombor menunjukkan nilai yang sama di bawah "Plug in your own system". Jika access_token ialah null, sambung semula nombor dari komputer dengan Reconnect untuk mengeluarkan token. Layan token seperti kata laluan, kerana sesiapa yang memegangnya boleh menghantar mesej sebagai perniagaan.
Kesilapan biasa
- Menyemak HMAC pada JSON yang disusun semula. json.dumps Python menambah ruang selepas pemisah secara lalai, jadi badan yang dihuraikan dan disusun semula tidak lagi sepadan; sahkan bait mentah.
- Menyahkod base64 pada rahsia atau membuang awalan whsec_. Kunci ialah keseluruhan rentetan sebagai teks UTF-8, tepat seperti yang ditunjukkan kepada anda sekali.
- Mengesahkan X-Hub-Signature-256 pada laluan terus dengan rahsia aplikasi Meta anda sendiri. Meta menandatangani dengan rahsia aplikasi easyCoexistence, yang tidak dikongsi, jadi acara tulen gagal; sahkan dengan rahsia laluan.
- Membaca tetingkap dari masa ketibaan. Pemajuan yang dicuba semula berjam-jam kemudian masih membawa cap masa asal Meta; bandingkan dengannya, atau ejen membalas selepas 24 jam dan Meta menolak penghantaran.
Setiap nombor dipantau 24/7, dengan amaran apabila sambungan terputus. Daripada US$ 9 turun ke US$ 0.75 setiap nombor sebulan, susut apabila anda menambah nombor, termasuk 3 hari percubaan percuma.
Soalan lazim
Bolehkah ejen memahami nota suara dan foto?
Ya, dengan kod anda sendiri. Muatan Meta membawa id media: muat turun dengan GET /<media-id> dan token nombor itu, dapatkan URL yang dipulangkan dengan header Authorization yang sama, kemudian tukarkan kepada teks atau huraikan dengan model anda. Automasi hanya nampak pemegang tempat seperti [voice message].
Apakah model yang boleh digunakan oleh sampel?
Mana-mana model di belakang endpoint chat completions yang serasi dengan OpenAI, termasuk milik OpenAI dan yang dicapai melalui OpenRouter, atau gantikan askModel dan ask_model dengan SDK pembekal anda. easyCoexistence tidak pernah mengenakan bayaran untuk AI: pembekal anda mengenakan bayaran terus kepada anda.
Bolehkah ejen memulakan perbualan?
Hanya dengan templat yang diluluskan, dihantar dengan type template ke send endpoint yang sama. Pada nombor Coexistence, templat dihantar melalui API sahaja, tidak sekali-kali dari aplikasi telefon, dan Meta mengenakan bayaran bagi setiap mesej kepada Akaun WhatsApp Business milik perniagaan itu.
Adakah satu ejen melayani beberapa nombor?
Ya. Halakan mengikut value.metadata.phone_number_id atau connection.phone_number_id, dan simpan send endpoint, token dan rahsia pemajuan bagi setiap nombor, kerana setiap nombor mempunyai miliknya sendiri.
Teruskan membaca
Sedia untuk bermula?
Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.
Mulakan Percubaan PercumaDisahkan pada