كيف تصل رسائل WhatsApp إلى خادمك: مباشرة أو مُدارة، والتحقق من التوقيع
لكل رقم متصل عبر easyCoexistence وضع واحد للرسائل الواردة. مباشرة إلى نظامك (مباشر): تنشر Meta خطافات الويب (webhooks) الخاصة بها إلى نقطة النهاية (endpoint) الخاصة بك عبر HTTPS، ويكون السر الموجود في عنوان URL هو بيانات الاعتماد، والأتمتة متوقفة. عبر easyCoexistence (مُدار): تسلّم Meta الرسائل إلى easyCoexistence، ويمكن للأتمتة أن ترد، ويتلقى عنوان URL للتوجيه الاختياري القيمة الأصلية من Meta مع تفاصيل الاتصال، موقّعة بـ X-EC-Signature لتتحقق منها بنفسك.
عدد المحاولات لكل عملية تسليم موجّهة، بفواصل زمنية: 1 دقيقة، 5 دقائق، 30 دقيقة، 2 ساعة، 6 ساعات و24 ساعة، أي نحو 33 ساعة في المجموع.
المدة التي تنتظرها كل محاولة توجيه للحصول على استجابة 2xx قبل أن تُحتسب فاشلة.
الحد المقترح لعمر قيمة t في التوقيع؛ تُوقَّع المحاولات من جديد، فتبقى عمليات التسليم الأصلية ضمن هذا الحد.
المدة التي تعيد فيها Meta محاولة الخطاف المباشر عند أي رد غير HTTP 200، وقد يؤدي ذلك إلى تكرار الرسائل.
أكبر حمولة لـ webhook ترسلها Meta، بما فيها أجزاء السجل.
مدة حفظ سجلات التشغيل للرقم المُدار مع نص الرسالة والرد، بينما يُحفظ نص الرسائل نفسه 30 أو 90 أو 365 يومًا، حسب اختيارك.
ما الفرق بين المباشر والمُدار؟
يحدد الوضع المكان الذي تسلّم Meta إليه webhooks رسائل الرقم. الوضع المُدار، ويظهر باسم عبر easyCoexistence، يعني أن Meta تسلّم الرسائل إلى easyCoexistence، فتتحقق من توقيع Meta، وتشغّل الأتمتة لديك، وتحفظ المحادثات لقسم المحادثات، وإذا حددت عنوان URL للتوجيه تمرّر إليك كل تغيير من Meta موقّعًا بسر لا يملكه إلا أنت. أما الوضع المباشر، ويظهر باسم مباشرة إلى نظامك، فيعني أن easyCoexistence تضبط نقطة نهاية HTTPS الخاصة بك كتجاوز لـ webhook في حساب WhatsApp Business للرقم، فتنشر Meta إليك مباشرةً ولا تصل الرسائل إلى easyCoexistence أبدًا.
تبقى webhooks التشغيلية التي تقوم عليها المراقبة، مثل account_update وتغييرات الجودة، لدى easyCoexistence في الوضعين، ولهذا تستمر التنبيهات في العمل في الحالتين.
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
كيف تبدّل الرقم بين الوضعين؟
في صفحة الرقم، تعرض بطاقة وجهة الرسائل الواردة الوضع في خيارين، هما عبر easyCoexistence ومباشرة إلى نظامك. حفظ وجهة webhook، في بطاقة توجيه الرسائل الواردة إلى webhook الخاص بك أو عبر set_webhook_destination، يجعل الرقم مباشرًا. اختيار عبر easyCoexistence يزيل تلك الوجهة لدى Meta فورًا، لذا أضف العنوان نفسه بوصفه عنوان URL للتوجيه كي تستمر في الاستلام. تُحذف عمليات التوجيه في قائمة الانتظار عند خروج الرقم من الوضع المُدار، والأرقام التي تُربط دون عنوان URL لـ webhook تبدأ مُدارة.
من مساعدك الذكي، يبدّل set_inbound_mode الوضع ويضبط التوجيه في استدعاء واحد، ويعيد السر الخاص بالتوجيه مرة واحدة فقط:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}ماذا يتضمن طلب POST المُوجَّه؟
تغيير واحد من Meta في كل طلب، مغلَّف، بدلًا من غلاف object وentry وchanges الخاص بـ Meta. id هو معرّف عملية التسليم، ويتكرر في X-EC-Delivery ويبقى ثابتًا عبر المحاولات. event هو اسم حقل Meta، وهو messages أو smb_message_echoes أو history أو smb_app_state_sync، ويتكرر في X-EC-Event. received_at هو وقت استلام easyCoexistence للتغيير من Meta، وconnection يحدد الرقم، وvalue هو ما أرسلته Meta بالضبط، فتعمل عليه الشيفرة المكتوبة لحمولة Meta كما هي. تصل حالات التسليم داخل أحداث messages، تحت value.statuses.
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}كيف تتحقق من X-EC-Signature في Node.js؟
اقرأ ترويسة التوقيع بصيغة t=<unix seconds>,v1=<64 hex characters>. ارفض أي t يبعد أكثر من 5 دقائق عن ساعتك، واحسب HMAC-SHA256 على t ونقطة ثم الجسم الخام، مع استخدام السر الكامل للتوجيه بصيغة نص UTF-8 مفتاحًا، وقارن النتيجة بـ v1 بزمن ثابت. عندها فقط حلّل JSON. أجب بـ 2xx خلال 10 ثوانٍ، ونفّذ العمل بعد ذلك، واحفظ معرّفات عمليات التسليم التي قبلتها كي لا تُعالَج المحاولة مرتين.
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);كيف تتحقق منه في Python؟
الفحوصات الأربعة نفسها بمكتبة Python القياسية: نمط صارم للترويسة، وعمر t، وhmac.new على t ونقطة ثم البايتات الخام، وhmac.compare_digest. في FastAPI يأتي الجسم الخام من await request.body()، ويشغّل BackgroundTasks العمل بعد إرسال الرد 200. في Flask، استخدم request.get_data()، ولا تُعِد بناء الجسم بـ json.dumps أبدًا، لأن الفواصل الافتراضية في Python تضيف مسافات فلا يتطابق التوقيع بعد ذلك.
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)كيف تُعاد محاولة عمليات التسليم الفاشلة؟
تُحسب عملية التوجيه مُسلَّمة حين يجيب endpoint لديك بأي استجابة 2xx خلال 10 ثوانٍ. وأي حالة أخرى، كانتهاء المهلة أو الرد 4xx أو 5xx أو إعادة توجيه لا تُتبع، تُجدول المحاولة التالية بعد نحو 1 دقيقة، و5 دقائق، و30 دقيقة، و2 ساعة، و6 ساعات، و24 ساعة، وبعد المحاولة السابعة تُهمل عملية التسليم. تُوقَّع كل محاولة من جديد بقيمة t جديدة، ويجب أن يكون عنوان URL عامًا عبر HTTPS، ويُفحص عند حفظه ومرة أخرى قبل كل إرسال. تُرسل عمليات التسليم الأقدم أولًا، لكن العملية المُعاد محاولتها قد تصل بعد أحدث منها، لذا رتّبها وفق الطوابع الزمنية لـ Meta.
في الوجهة المباشرة تتولى Meta إعادة المحاولة: كل ما عدا HTTP 200 يُعاد إرساله بتكرار يقل تدريجيًا لمدة تصل إلى 7 أيام، وقد تكرر هذه المحاولات رسالة. أزل التكرار بالاعتماد على معرّف الرسالة لدى Meta في الوضعين، لأن التغيير الذي تعيد Meta تسليمه يُوجَّه مرة أخرى بمعرّف تسليم جديد.
كيف يتأكد endpoint المباشر أن طلب POST أصلي؟
لا تعتمد على X-Hub-Signature-256. توقّع Meta بالسر الخاص بالتطبيق الذي يملك الاشتراك، وهو بالنسبة للرقم المتصل هنا سر easyCoexistence غير المشترك، لذا فإن فحص هذه الترويسة بسر تطبيق Meta الخاص بك يرفض عمليات التسليم الأصلية. رمز التحقق (verify token) لا يثبت endpoint إلا مرة واحدة، أثناء مصافحة GET لدى Meta. ما ينجح بدلًا من ذلك:
- ضع 32 حرفًا عشوائيًا أو أكثر في مسار عنوان URL للاستدعاء، وارفض الطلبات التي لا تحملها؛ ولتدويره، احفظ عنوان URL جديدًا.
- استخدم مستقبلًا عامًا، مثل عقدة n8n Webhook، لا مشغّل WhatsApp الذي يتوقع تطبيق Meta خاصًا بك.
- نزّل الوسائط بمعرّفها من Meta باستخدام رمز الوصول (token) الخاص بالرقم، فيفشل المعرّف المزوّر ببساطة.
- على الخوادم المستضافة ذاتيًا، يمكنك اختياريًا السماح فقط بشبكة Meta، أي المسارات التي تعلن عنها AS32934.
- أو انتقل إلى الوضع المُدار مع عنوان URL للتوجيه، حيث يثبت X-EC-Signature كل طلب POST.
الأخطاء الشائعة
- توجيه كود مكتوب لغلاف Meta إلى عنوان URL للتوجيه دون تعديل. تحمل عملية التوجيه تغييرًا واحدًا: اقرأ event وvalue، لا object وentry وchanges.
- انتظار X-EC-Event بقيمة statuses. تأتي حالات التسليم داخل أحداث messages، في value.statuses، والردود المكتوبة في التطبيق تأتي بوصفها smb_message_echoes.
- تنفيذ العمل قبل الرد. تنتظر عملية التوجيه 10 ثوانٍ، ثم تعود عملية التسليم نفسها بقيمة t جديدة؛ أجب بـ 2xx أولًا، وعالج من طابور.
- التحول إلى الوضع المُدار مع افتراض أن العنوان القديم ما زال يستقبل. تُزال الوجهة المباشرة في تلك اللحظة؛ مرّر forward_url في استدعاء set_inbound_mode نفسه.
تربط easyCoexistence رقم تطبيق WhatsApp Business بواجهة Cloud API من Meta عبر Coexistence، وتتيح لك أن تختار لكل رقم وجهة رسائله: مباشرة من Meta إلى خادمك، أو عبر easyCoexistence لتردّ الأتمتة وتصل نسخة موقّعة إلى عنوان URL للتوجيه. تعمل المراقبة والتنبيهات في الوضعين. من US$ 9 إلى US$ 0.75 لكل رقم في الشهر، ويقل السعر كلما أضفت أرقامًا، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل سيرى خادمي ما ردّت به الأتمتة؟
ليس النص. تُبلغ Meta عن عمليات الإرسال عبر واجهة برمجة التطبيقات (API) بوصفها حالات (sent وdelivered وread) داخل أحداث messages، مع معرّف الرسالة؛ أما النص نفسه فيوجد في سجل تشغيل الأتمتة، ويُحفظ 30 يومًا في تبويب التشغيلات، وفي المحادثات للمدة التي اخترتها.
كيف أدوّر السر الخاص بالتوجيه؟
انقر على سر جديد في صفحة الرقم، أو استدعِ set_inbound_mode مع rotate_secret بقيمة true. يُعرض السر الجديد مرة واحدة ويوقّع كل ما يأتي بعد ذلك، بما فيه إعادة محاولة عمليات التسليم الأقدم، لذا حدّث خادمك فورًا.
هل يحتاج عنوان URL للتوجيه إلى مصافحة GET لدى Meta؟
لا. الوجهة المباشرة وحدها هي التي تستدعيها Meta، ويجب أن تردّ بقيمة hub.challenge. أما عنوان URL للتوجيه فتستدعيه easyCoexistence ولا يستقبل سوى طلبات POST موقّعة.
هل يمكن أن تكون للرقم وجهة مباشرة وعنوان URL للتوجيه في الوقت نفسه؟
لا. يعمل عنوان URL للتوجيه فقط ما دام الرقم مُدارًا، وحفظ وجهة مباشرة يجعله مباشرًا. يُحتفظ بعنوان URL للتوجيه وسره، لذا فالعودة إلى الوضع المُدار تستأنف التوجيه.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في