كيف تعرف متى ينقطع اتصال واتساب أو حساب التواصل الاجتماعي لعميلك
يرسل easyCoexistence إلى منصتك أحداث حالة موقّعة عندما يُربط اتصال عميلك أو ينقطع أو يُزال أو يُعلَّق. يرسل رقم واتساب الأحداث connection.connected وconnection.disconnected مع سبب Meta وconnection.removed وconnection.suspended أو connection.token_missing، ويرسل حساب التواصل الاجتماعي ما يقابلها من أحداث channel.*، دون token_missing. كل حدث طلب POST بصيغة JSON موقّع بالترويسة X-EC-Signature، ويُعاد إرساله بتأخير متزايد لنحو 33 ساعة حتى ترد نقطة النهاية (endpoint) برمز 2xx.
PRIMARY_INACTIVITY: سبب تحدده Meta عندما يبقى الجهاز الأساسي غير نشط نحو 14 يومًا، فيُفصل رقم Coexistence.
COMPANION_INACTIVITY: سبب تحدده Meta عندما يبقى جهاز مرافق غير نشط نحو 30 يومًا.
خطاف الويب (webhook) الذي يُبلّغ عن الانقطاع. ترسله Meta دائمًا إلى عنوان URL الافتراضي للاستدعاء في التطبيق، ولا ترسله أبدًا إلى أي عنوان تجاوز.
عدد مرات إعادة محاولة الحدث عند أي استجابة خارج 2xx، بفواصل من دقيقة واحدة إلى 24 ساعة، على مدى نحو 33 ساعة.
أقدم طابع زمني موقّع t يجب أن تقبله نقطة النهاية لحدث الحالة، مع مقارنة HMAC بزمن ثابت.
ما أحداث الحالة المتوفرة؟
تسعة أحداث في فئتين تشتركان في نقطة نهاية واحدة ومفتاح توقيع واحد. تستخدم الأرقام connection.* وتستخدم حسابات التواصل الاجتماعي channel.*، لذلك يستطيع مستقبِل مكتوب للأرقام أن يتجاهل أحداث channel بالاسم. اضبط عنوان نقطة النهاية من لوحة التحكم عبر الملف الشخصي ثم المطورون، أو باستخدام أداة MCP باسم set_partner_events_url. يظهر مفتاح التوقيع مرة واحدة فقط عند حفظ العنوان.
ماذا يحمل حدث الاتصال؟
معرّف التسليم id وهو UUID، واسم الحدث، وoccurred_at بصيغة ISO 8601، وكائن connection يحتوي على id وexternal_ref وconnect_session_id وphone وname وwaba_id وphone_number_id وstatus وtoken_ready. تضيف بعض الأحداث حقلًا على المستوى العلوي: reason في connection.disconnected وconnection.suspended، وdetected_by بقيمة health_check عندما يكتشف الفحص الدوري لـ easyCoexistence الانقطاع بدلًا من webhook الذي ترسله Meta، وconnect_session_id عندما تنتجه جلسة ربط.
{
"id": "5c2a9e70-…",
"event": "connection.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"connection": {
"id": "<CONNECTION_ID>",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"phone": "+55 11 9…",
"name": "Clínica Sorriso",
"waba_id": "<WABA_ID>",
"phone_number_id": "<PHONE_NUMBER_ID>",
"status": "disconnected",
"token_ready": true
},
"reason": "PRIMARY_INACTIVITY"
}ماذا يحمل حدث القناة؟
الغلاف نفسه مع كائن channel بدل connection، وهو عرض GET /channels/{id}: id وchannel للشبكة وexternal_ref وconnect_session_id وname وusername وexternal_id وstatus وtoken_ready وwebhook_url وdisconnected_reason وlast_checked_at وcreated_at. لا يوجد token_missing للقنوات، لأن تسجيل الدخول عبر التواصل الاجتماعي يعطي دائمًا رمز الوصول الخاص بالعميل نفسه. ويحمل channel.connected الناتج عن جلسة ربط connect_session_id على المستوى العلوي أيضًا.
{
"id": "0b7e41d2-…",
"event": "channel.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"channel": {
"id": "<CHANNEL_ID>",
"channel": "tiktok",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"name": "Clínica Sorriso",
"username": "clinicasorriso",
"external_id": "<TIKTOK_OPEN_ID>",
"status": "disconnected",
"token_ready": false,
"webhook_url": "https://hooks.example.com/social",
"disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
"last_checked_at": "2026-10-31T10:15:02.000Z",
"created_at": "2026-10-28T16:40:09.000Z"
}
}ماذا تعني أسباب الانقطاع؟
reason في connection.disconnected هو الرمز الذي وضعته Meta في disconnection_info ضمن webhook من نوع account_update، وتُدرجه Meta للأرقام على تطبيق واتساب Business وعلى Cloud API. ويكون null عندما لا تُرفق Meta سببًا. الرموز في مرجع Meta:
PRIMARY_INACTIVITY: كان الهاتف الذي يشغّل تطبيق واتساب Business غير نشط نحو 14 يومًا، وهي قاعدة الـ 14 يومًا. تعيد جلسة ربط جديدة وصل الرقم.ACCOUNT_DISCONNECTED: فُصل الحساب عبر إجراء إنفاذ من Meta أو من العميل، وقد يكون العميل قد أزال الوصول أو حذف الحساب.COMPANION_INACTIVITY: كان جهاز مرافق غير نشط نحو 30 يومًا.BUSINESS_DOWNGRADE: سُجّل الرقم في تطبيق واتساب الاستهلاكي.CHANGE_NUMBERوUSER_RE_REGISTERED: غيّر العميل الرقم، أو سجّله من جديد على جهاز جديد.
ما الترويسات المرفقة بحدث الحالة؟
خمس ترويسات في كل محاولة: Content-Type بقيمة application/json، وUser-Agent بقيمة easyCoexistence-webhooks/1، وX-EC-Event باسم الحدث، وX-EC-Delivery بالمعرّف نفسه الموجود في الجسم، وX-EC-Signature. يأتي التوقيع بصيغة t=<unix>,v1=<hex>، حيث v1 هو HMAC-SHA256 للقيمة t ثم نقطة ثم الجسم الخام، ويُحسب بمفتاح توقيع حسابك الذي يبدأ بـ whsec_. يُوقَّع كل محاولة من جديد، فتحمل إعادة المحاولة قيمة t جديدة للجسم نفسه.
import hashlib, hmac, json, os, time
SECRET = os.environ["EC_EVENTS_SECRET"].encode() # whsec_..., shown once in Profile > Developers
def verify(raw: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, or more than 5 minutes off
mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
def handle(raw: bytes, headers) -> int:
if not verify(raw, headers.get("X-EC-Signature", "")):
return 401
event = json.loads(raw)
if already_processed(event["id"]): # the X-EC-Delivery id, the same on every retry
return 200
enqueue(event) # act on event["event"]; the latest occurred_at wins
return 200كيف تُعاد محاولة التسليمات الفاشلة؟
تُرسل المحاولة الأولى لحظة وقوع الحدث. تُعد أي استجابة خارج 2xx، أو عدم الرد خلال 10 ثوانٍ، أو خطأ شبكة، أو إعادة توجيه، فشلًا، فيُعاد محاولة الحدث بفواصل متزايدة، من دقيقة واحدة إلى 24 ساعة، بسبع محاولات في المجموع على مدى نحو 33 ساعة، ثم يُسقط. تُرسل التسليمات فقط إلى عنوان HTTPS يُحل إلى IP عام. لا يُحفظ في قائمة انتظار حدثٌ يقع بينما لا توجد نقطة نهاية، وإزالة نقطة النهاية توقف كل ما هو معلّق.
لماذا تعالج كل معرّف مرة واحدة وتتحقق من occurred_at؟
لأن إعادة المحاولة تكرر التسليم حرفيًا، بالمعرّف نفسه في الجسم وفي X-EC-Delivery، ولأن الحدث المعاد قد يصل بعد حدث أحدث. احفظ المعرّفات التي عالجتها وتجاوز المكررات. ثم قارن occurred_at بآخر حالة سجلتها لذلك الاتصال، أو اقرأ GET /connections/{id} أو GET /channels/{id} قبل التصرف في حدث قد يكون قديمًا.
ماذا ينبغي أن تفعل المنصة عند انقطاع رقم؟
تصرّف بحسب السبب. بعد PRIMARY_INACTIVITY، اطلب من العميل فتح تطبيق واتساب Business، ثم أرسل له جلسة ربط جديدة للرقم نفسه. إعادة ربطه على حساب واتساب Business نفسه تحفظ معرّف اتصاله، وتعيد وجهة الـ webhook الخاصة بك، وترسل connection.connected، وبعدها تقرأ بيانات اعتماده من جديد. أما connection.token_missing فيعني أن Meta لم تُصدر رمزًا في تلك المحاولة. ترسل Meta حدث account_update المرتبط بالانقطاع إلى عنوان الاستدعاء الخاص بالتطبيق وحده، لا إلى عنوانك، لذلك يبلغك هذا الحدث بالانقطاع.
ماذا ينبغي أن تفعل المنصة عند انقطاع حساب تواصل اجتماعي؟
عند channel.disconnected، تعيد جلسة ربط جديدة بالقناة نفسها تسجيل دخول الحساب تحت معرّف القناة نفسه. يعني channel.removed أن الوصول قد زال: يُنسى الرمز وتُمسح وجهة الـ webhook، لذا أعد ضبط الوجهة إذا أعاد العميل الربط. ويعود الرقم أو القناة المعلّقة بعد إعادة تفعيل اشتراكك، عبر إعادة ربطها مرة واحدة.
الأخطاء الشائعة
- اعتبار إعادة المحاولة حدثًا جديدًا. تحمل المعرّف نفسه في الجسم وفي X-EC-Delivery، فسجّل المعرّفات المعالجة، وإلا قد ينبّه انقطاع واحد العميل مرتين.
- معالجة الأحداث بترتيب الوصول. قد يصل حدث معاد بعد حدث أحدث، لذا قارن occurred_at، أو اقرأ الاتصال قبل التصرف.
- حفظ عنوان الأحداث من جديد لتصحيح خطأ مطبعي دون تحديث الخادم. يصدر الحفظ مفتاح توقيع جديدًا، ويفشل التحقق في كل تسليم حتى تستخدمه نقطة النهاية.
- تنفيذ العمل قبل الرد. المعالج الذي يستغرق أكثر من 10 ثوانٍ يُحسب فاشلًا فيعود الحدث، لذا أجب 2xx أولًا ثم عالج لاحقًا.
يراقب easyCoexistence أرقام واتساب وحسابات التواصل الاجتماعي لعملائك على مدار الساعة، ويرسل إلى منصتك حدثًا موقّعًا عند ربط أي منها أو انقطاعه أو إزالته أو تعليقه، مع سبب Meta عند انقطاع رقم. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
ما معنى PRIMARY_INACTIVITY؟
هو سبب تحدده Meta لفصل رقم Coexistence، عندما يبقى تطبيق واتساب Business غير مستخدم على جهازه الأساسي نحو 14 يومًا. تعيد جلسة ربط جديدة لذلك العميل وصل الرقم.
هل تتضمن أحداث الحالة الرسائل؟
لا. تغطي حالة الاتصال فقط. تنتقل رسائل الرقم من Meta إلى وجهة الـ webhook الخاصة به، وتنتقل تعليقات التواصل الاجتماعي والرسائل المباشرة إلى وجهة كل قناة.
أين أضبط عنوان الأحداث؟
من لوحة التحكم عبر الملف الشخصي ثم المطورون، أو باستخدام أداة MCP باسم set_partner_events_url. يظهر مفتاح التوقيع مرة واحدة، وحفظ العنوان من جديد يصدر مفتاحًا جديدًا.
هل يمكنني تجاهل أحداث القنوات إذا كنت أتعامل مع الأرقام فقط؟
نعم. لأحداث channel.* أسماء خاصة بها، وتحمل كائن channel بدلًا من connection، فيستطيع المستقبِل تجاهل أي حدث لا يبدأ اسمه بـ connection.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في