بناء وكيل ذكاء اصطناعي لـ WhatsApp بـ Node.js وPython على رقم Coexistence
استلم رسائل الرقم إما مُعاد توجيهها مع توقيع HMAC تتحقق منه (X-EC-Signature)، أو مباشرة من خطاف الويب (webhook) الخاص بـ Meta مع سر داخل عنوان URL. ثم تجاهل أي معرّف رسالة سبق معالجته، ولا ترد في محادثة يُظهر فيها حدث echo أن شخصاً ردّ من الهاتف، وأرسل إجابة نموذجك عبر Cloud API فقط ضمن 24 ساعة من آخر رسالة للعميل.
تربط easyCoexistence الرقم الذي يواصل النشاط التجاري استخدامه في تطبيق WhatsApp Business بواجهة Cloud API من Meta، وتمنح كودك بيانات اعتماده عبر get_api_credentials، وتوجّه الرسائل مباشرة من Meta إلى خادمك أو عبر إعادة توجيه موقّعة مع تشغيل الأتمتة.
أكبر فارق يُقبل بين t في التوقيع وساعتك؛ كل إعادة محاولة تُوقَّع من جديد بقيمة t جديدة.
المدة التي ينتظرها طلب POST المُعاد توجيهه للحصول على استجابة 2xx قبل أن تجدول easyCoexistence إعادة محاولة لذلك التسليم.
المدة التي تعيد فيها Meta محاولة إرسال webhook مباشر لم يحصل على HTTP 200، وقد يؤدي ذلك إلى تسليم الرسالة نفسها مرتين.
نافذة خدمة العملاء بعد آخر رسالة من المستخدم؛ خارجها تقبل Meta رسائل القوالب فقط.
معدل الإنتاجية الثابت لرقم يُستخدم مع تطبيق WhatsApp Business وCloud API معاً.
أي مسار يجب أن يستخدمه الوكيل المكتوب بالكود؟
المسار المُعاد توجيهه يعني أن الرقم يبقى في وضع تشغيل الأتمتة (On): تُسلّم Meta الأحداث إلى easyCoexistence، ويمكن للأتمتة أن تعمل، وتُرسل نسخة موقّعة من كل تغيير من Meta إلى Forward URL لديك. وهناك صيغة لا تحتاج إلى إعادة توجيه أصلاً: خطوة الأتمتة Call my webhook ترسل الرسالة بطريقة POST إلى نقطة النهاية (endpoint) لديك، وترسل أي {"reply"} تعيده خلال 20 ثانية، مع إزالة التكرار وإيقاف الرد عند رد شخص وفحص نافذة 24 ساعة نيابةً عنك.
المسار المباشر يعني أن Meta ترسل webhook الخاص بها مباشرة إلى endpoint لديك، المعيّنة بـ set_webhook_destination، ولا ترى easyCoexistence الرسائل أبداً. الأتمتة متوقفة لذلك الرقم، لذا كل الحمايات عليك، وكذلك استيراد سجل 6 أشهر عند حفظ الوجهة خلال 24 ساعة من الربط. تغطي الأمثلة أدناه نقاط الدخول الثلاث بنواة مشتركة واحدة.
| 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 |
ماذا يفعل الوكيل بالرسالة في Node.js؟
يحتوي agent.mjs على المنطق الذي يتشاركه المساران. يسجّل وقت آخر رسالة للعميل، ويتوقف عن الرد في المحادثة لمدة 4 ساعات عندما يُظهر حدث smb_message_echoes أن شخصاً ردّ من تطبيق WhatsApp Business (وهذا هو الافتراضي في أتمتة easyCoexistence)، ويتجاهل معرّف رسالة سبق معالجته، ولا يرسل إلا داخل نافذة 24 ساعة. تُحسب النافذة من الطابع الزمني للرسالة نفسها، لا من لحظة وصولها إليك، لأن التسليم المُعاد قد يصل متأخراً ساعات.
يُعرَّف المستخدمون بـ BSUID (من from_user_id، أو to_user_id في أحداث echo) مع رقم الهاتف كبديل، ويُرد على المستخدم الذي لا يُعرف إلا بـ BSUID عبر recipient بدلاً من to. يستخدم استدعاء النموذج أي واجهة chat completions متوافقة مع OpenAI؛ استبدلها بحزمة SDK الخاصة بمزوّدك إن شئت.
// 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()}`);
}كيف تتحقق من الأحداث وتوجّهها في Node.js؟
يعرض server.mjs نقاط الدخول الثلاث. يستقبل /ec/forward عمليات إعادة التوجيه من رقم مُدار: يتحقق من X-EC-Signature على البايتات الخام باستخدام سر إعادة التوجيه الخاص بالرقم، ويرد بـ 200 قبل أي عمل، ويتجاهل معرّف تسليم سبق قبوله، لأن إعادة المحاولة تحمل المعرّف نفسه بتوقيع جديد. الحقل event في الجسم هو اسم الحقل في Meta، وvalue هو التغيير الصادر من Meta دون تعديل. يستجيب /ec/agent لخطوة Call my webhook، ويتحقق من التوقيع بـ Signing secret الخاص بتلك الأتمتة، ويحوّل السجل إلى أدوار محادثة. أما /meta/:secret فهو المسار المباشر: يرد على مصافحة GET من Meta بقيمة hub.challenge الخام، ويقبل طلبات POST على مسار السر فقط.
مفتاح HMAC هو السر كاملاً، بما فيه البادئة whsec_، كنص UTF-8. يُبقي express.raw البايتات سليمة، وحدّه البالغ 5 MB يترك مساحة لحمولات Meta التي تصل إلى 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);كيف يبدو الوكيل نفسه في Python؟
ملف Flask واحد بالمسارات الثلاثة نفسها والقواعد نفسها. تعيد request.get_data() الجسم الخام لحساب HMAC، وتتولى hmac.compare_digest المقارنة ثابتة الزمن، ويعمل التنفيذ في خيط خلفي بعد الرد بـ 200، فلا تنتظر easyCoexistence ولا Meta نموذجك. شغّله بـ flask --app agent run أثناء التطوير، وخلف gunicorn أو خادم WSGI آخر في الإنتاج.
تناسب المجموعة والقواميس في الذاكرة عملية واحدة فقط. مع عدة عمليات عاملة أو نسخ، انقلها إلى Redis أو قاعدة بياناتك، باستخدام كتابة set-if-absent مع مدة انتهاء لمعرّفات الرسائل، وإلا فسترد عمليتان على الرسالة نفسها.
# 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كيف تتجنب الردود المكررة؟
للتكرار ستة أسباب شائعة، وتعالج الأمثلة أعلاه الخمسة الأولى:
- إعادات محاولة Meta. تعيد Meta محاولة إرسال webhook المباشر حتى 7 أيام بعد أي استجابة غير HTTP 200؛ احتفظ بمخزن لمعرّفات الرسائل وتجاهل المعرّفات التي سبقت معالجتها.
- إعادات محاولة إعادة التوجيه. تعيد easyCoexistence محاولة التسليم الذي لم يحصل على 2xx خلال 10 ثوانٍ، بالمعرّف نفسه؛ تجاهل المعرّفات المقبولة سابقاً، ثم أزل التكرار بمعرّف الرسالة، لأن التغيير الذي تعيد Meta تسليمه يُعاد توجيهه بمعرّف جديد.
- تأكيد استلام بطيء. أجب أولاً ثم اعمل؛ فالمعالج الذي ينتظر النموذج تنتهي مهلته فيعود الحدث نفسه.
- شخص على الهاتف. حدث
smb_message_echoesيعني أن أحداً ردّ من التطبيق؛ لا ترد في تلك المحادثة لبضع ساعات. - عدة عمليات عاملة. لا تمتد المجموعات في الذاكرة عبر العمليات؛ انقل المخازن إلى Redis أو قاعدة بياناتك.
- جهتا رد. أتمتة الرد بالذكاء الاصطناعي ووكيلك يجيبان على المحادثات نفسها، ولا تُعد رسائلك المرسلة عبر Graph API أحداث echo، فلا توقف الأتمتة. اختر جهة رد واحدة لكل رقم.
من أين تأتي الأسرار وبيانات الاعتماد؟
من لوحة التحكم أو موصل MCP، ويجب ألا توضع إلا في متغيرات بيئة خادمك. تُرجع get_api_credentials القيم graph_api_base وwaba_id وphone_number_id وsend_endpoint وaccess_token، وهو رمز الوصول (token) الخاص بالنشاط التجاري نفسه؛ وتعرض صفحة الرقم القيم نفسها تحت Plug in your own system. إذا كانت قيمة access_token تساوي null، فأعد ربط الرقم من حاسوب باستخدام Reconnect لإصدار token. عامل الـ token كما تعامل كلمة المرور، لأن من يحمله يستطيع المراسلة باسم النشاط التجاري.
الأخطاء الشائعة
- التحقق من HMAC على JSON أُعيد تسلسله. تضيف json.dumps في Python مسافات بعد الفواصل افتراضياً، فالجسم الذي يُحلَّل ثم يُسلسَل من جديد لا يطابق التوقيع؛ تحقق من البايتات الخام.
- فك ترميز السر بـ Base64 أو حذف بادئته whsec_. المفتاح هو السلسلة كاملة كنص UTF-8، تماماً كما عُرضت لك مرة واحدة.
- التحقق من X-Hub-Signature-256 على المسار المباشر باستخدام سر تطبيق Meta الخاص بك. توقّع Meta بسر تطبيق easyCoexistence، وهو غير مشارك، فتفشل الأحداث الأصلية؛ لذا صادِق بسر المسار.
- قراءة النافذة من وقت الوصول. التسليم المُعاد بعد ساعات يحمل الطابع الزمني الأصلي من Meta؛ قارن به، وإلا فسيرد الوكيل بعد 24 ساعة وترفض Meta الإرسال.
يُراقَب كل رقم على مدار الساعة، مع تنبيهات عند انقطاع الاتصال. من US$ 9 إلى US$ 0.75 لكل رقم شهرياً، ينخفض كلما أضفت أرقاماً، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل يستطيع الوكيل فهم الرسائل الصوتية والصور؟
نعم، بكودك الخاص. تحمل حمولة Meta معرّف الوسائط: نزّله بـ GET /<media-id> وبـ token الرقم، ثم اجلب عنوان URL المُعاد بترويسة Authorization نفسها، ثم حوّل الصوت إلى نص أو صِف الصورة بنموذجك. لا ترى الأتمتة إلا عناصر نائبة مثل [voice message].
أي النماذج يمكن أن تستخدمها الأمثلة؟
أي نموذج خلف endpoint من نوع chat completions متوافق مع OpenAI، بما فيها نماذج OpenAI وتلك التي يُوصل إليها عبر OpenRouter، أو استبدل askModel وask_model بحزمة SDK الخاصة بمزوّدك. لا تفرض easyCoexistence أي رسوم على الذكاء الاصطناعي؛ مزوّدك يحاسبك مباشرة.
هل يستطيع الوكيل بدء محادثة؟
فقط بقالب معتمد، يُرسل بـ type template إلى send endpoint نفسه. على رقم Coexistence تُرسل القوالب عبر واجهة برمجة التطبيقات (API) فقط، لا من تطبيق الهاتف، وتحاسب Meta عليها لكل رسالة في WhatsApp Business Account الخاص بالنشاط التجاري.
هل يخدم وكيل واحد عدة أرقام؟
نعم. وجّه بحسب value.metadata.phone_number_id أو connection.phone_number_id، واحتفظ بـ send endpoint وtoken وسر إعادة توجيه لكل رقم، لأن لكل رقم قيمه الخاصة.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في