تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

كيف تعرف متى ينقطع اتصال واتساب أو حساب التواصل الاجتماعي لعميلك

يرسل easyCoexistence إلى منصتك أحداث حالة موقّعة عندما يُربط اتصال عميلك أو ينقطع أو يُزال أو يُعلَّق. يرسل رقم واتساب الأحداث connection.connected وconnection.disconnected مع سبب Meta وconnection.removed وconnection.suspended أو connection.token_missing، ويرسل حساب التواصل الاجتماعي ما يقابلها من أحداث channel.*، دون token_missing. كل حدث طلب POST بصيغة JSON موقّع بالترويسة X-EC-Signature، ويُعاد إرساله بتأخير متزايد لنحو 33 ساعة حتى ترد نقطة النهاية (endpoint) برمز 2xx.

~14 days

PRIMARY_INACTIVITY: سبب تحدده Meta عندما يبقى الجهاز الأساسي غير نشط نحو 14 يومًا، فيُفصل رقم Coexistence.

~30 days

COMPANION_INACTIVITY: سبب تحدده Meta عندما يبقى جهاز مرافق غير نشط نحو 30 يومًا.

account_update

خطاف الويب (webhook) الذي يُبلّغ عن الانقطاع. ترسله Meta دائمًا إلى عنوان URL الافتراضي للاستدعاء في التطبيق، ولا ترسله أبدًا إلى أي عنوان تجاوز.

7 attempts

عدد مرات إعادة محاولة الحدث عند أي استجابة خارج 2xx، بفواصل من دقيقة واحدة إلى 24 ساعة، على مدى نحو 33 ساعة.

5 minutes

أقدم طابع زمني موقّع t يجب أن تقبله نقطة النهاية لحدث الحالة، مع مقارنة HMAC بزمن ثابت.

ما أحداث الحالة المتوفرة؟

تسعة أحداث في فئتين تشتركان في نقطة نهاية واحدة ومفتاح توقيع واحد. تستخدم الأرقام connection.* وتستخدم حسابات التواصل الاجتماعي channel.*، لذلك يستطيع مستقبِل مكتوب للأرقام أن يتجاهل أحداث channel بالاسم. اضبط عنوان نقطة النهاية من لوحة التحكم عبر الملف الشخصي ثم المطورون، أو باستخدام أداة MCP باسم set_partner_events_url. يظهر مفتاح التوقيع مرة واحدة فقط عند حفظ العنوان.

connection.connectedA number connected, came back after a drop, or got its customer token on a second run.
connection.disconnectedMeta dropped the link; reason carries Meta's code when known.
connection.removedRemoved with DELETE /connections/{id} or from the dashboard.
connection.suspendedYour subscription lapsed; reason names its state.
connection.token_missingConnected without a customer token: it receives, but cannot send yet.
channel.connectedA social account connected, one event per Page when a sign-in brings several.
channel.disconnectedThe network refused the token, or the owner withdrew access.
channel.removedRemoved with DELETE /channels/{id} or from the dashboard, or the owner removed the app on Meta.
channel.suspendedYour subscription lapsed.

ماذا يحمل حدث الاتصال؟

معرّف التسليم 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 عندما تنتجه جلسة ربط.

connection.disconnected
{
  "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 على المستوى العلوي أيضًا.

channel.disconnected
{
  "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 جديدة للجسم نفسه.

Python: verify, then handle each id once
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

يراقب 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.

تابع القراءة

كيف تستقبل عبر خطاف الويب (webhook) رسائل عملائك على WhatsApp وتعليقات مواقع التواصلwebhook لكل اتصال: رسائل WhatsApp مباشرة من Meta موثّقة بسر في عنوان URL، وتعليقات ورسائل مباشرة من منصات التواصل موقّعة بترويسة X-EC-Signature لكل حساب.كيف تحصل على رموز الوصول الخاصة بعملائك لـ WhatsApp وInstagram وTikTokما يعيده طلب credentials لرقم WhatsApp لعميلك ولكل حساب اجتماعي، حقلاً حقلاً، وكيف يعمل تجديد الرموز وحالة الجاهزية.كيفية استيراد سجل محادثات تطبيق WhatsApp Business وجهات الاتصال عبر واجهة برمجة التطبيقات (API)استيراد جهات الاتصال والمحادثات حتى 180 يومًا لأرقام تطبيق WhatsApp Business عبر Coexistence، مع تتبع chunk_order والتقدم.كيف تبني منتج وكيل ذكاء اصطناعي على WhatsApp وInstagram وTikTok لعملائكابنِ منتج وكيل ذكاء اصطناعي على WhatsApp وInstagram وFacebook وTikTok لعملائك عبر Partner API مع نموذجك وقواعد كل شبكة.خطاف الويب (webhook) account_update وجميع أسباب انقطاع الاتصاليُبلغ account_update عن تغيّر حالة الاتصال، ويعرض أسباب الانقطاع التي ترسلها Meta ومعنى كل سبب وإمكان استعادة الاتصال.توقف رقم عن العمل: كيف تعرف السببقائمة فحص مرتبة حسب تسلسل الأعطال الفعلي: رمز الوصول، خطاف الويب، انقطاع الخمول، الجودة، وتقييد الحساب.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في