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

كيف تتيح لعملائك ربط حسابات WhatsApp وInstagram وTikTok بتطبيقك

لتتيح لعملائك ربط حسابات WhatsApp وInstagram وTikTok بتطبيقك، أنشئ جلسة اتصال عبر Partner API الخاصة بـ easyCoexistence، ثم أرسل المستخدم إلى رابطها المستضاف. هناك يربط رقم WhatsApp عبر Embedded Signup من Meta، أو يسجل الدخول إلى Instagram وFacebook وTikTok وYouTube وLinkedIn وقنوات أخرى، ثم يعود إلى redirect_url لديك مع معرّف الاتصال أو القناة الجديد. تبقى الروابط صالحة ساعة واحدة.

1 hour

المدة التي يعمل فيها رابط الاتصال؛ بعدها تظهر الجلسة كمنتهية ويلزم رابط جديد.

50 open

يمكن لحساب واحد أن يفتح جلسات اتصال في الوقت نفسه، إلى جانب حد 100 جلسة جديدة في الساعة.

5 statuses

تُنشأ الجلسة ثم تُفتح وتُتصل أو تُلغى أو تنتهي، كما يوضح GET /connect-sessions/:id.

200 characters

أطول عنوان رد اتصال بديل تقبله Meta لتوجيه رسائل خطاف الويب (webhook) لرقم WhatsApp إلى جهة أخرى.

كيف يعمل رابط الاتصال؟

يشبه صفحة الدفع. يُنشئ الخادم الخلفي لديك جلسة، ثم ترسل واجهتك العميل إلى رابطها، فيتصل العميل من صفحة على easycoexistence.com، ويعود المتصفح إلى redirect_url لديك. بعد ذلك يتحقق الخادم الخلفي من النتيجة ويجلب بيانات اعتماد الاتصال الجديد، وكل ذلك بمفتاح API الخاص بك.

1CreatePOST /connect-sessions from your backend
2SendA redirect or a new tab to the session's url
3ConnectMeta's Embedded Signup, or the network's own sign-in
4ReturnYour redirect_url, with the session, status and new id
5ConfirmGET /connect-sessions/:id, then the credentials

ما الذي يتضمنه الطلب؟

يُرسل جسم JSON إلى https://easycoexistence.com/api/v1/connect-sessions، مع مفتاح API الخاص بك كرمز Bearer. الحقل الوحيد المطلوب هو redirect_url:

  • redirect_url: عنوان URL من نوع https يصل إليه العميل بعد ذلك.
  • channel: whatsapp، وهو الافتراضي، أو شبكة تواصل اجتماعي مفتوحة لحسابك، باسمها بحروف صغيرة، مثل instagram أو tiktok أو youtube.
  • external_ref: معرّفك الخاص لهذا العميل، بحد أقصى 200 حرف.
  • partner_name: الاسم الذي تعرضه الصفحة المستضافة، بحد أقصى 80 حرفًا؛ واسم حسابك افتراضيًا.
  • webhook_url مع webhook_verify_token: للأرقام فقط، ويُرسلان معًا دائمًا. تسلّم Meta رسائل الرقم إلى هذا العنوان من لحظة اتصاله.
Create a session for a WhatsApp number
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
  -H "Authorization: Bearer $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "redirect_url": "https://app.example.com/connect/return",
    "external_ref": "customer_4821",
    "partner_name": "ClinicApp",
    "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
    "webhook_verify_token": "another-long-random-string"
  }'

ما الذي يُعاد؟

استجابة 201 تتضمن الجلسة. أرسل العميل إلى url، واحتفظ بالمعرّف id، الذي يبدأ بـ cs_، للاستعلام عن الجلسة لاحقًا. يحل expires_at بعد ساعة من الإنشاء، ويُملأ connection_id أو channel_id بعد أن يتصل العميل، بحسب قناة الجلسة. يعيد GET /connect-sessions/:id الشكل نفسه في أي وقت.

201 Created
{
  "id": "cs_…",
  "url": "https://easycoexistence.com/connect/cs_…",
  "channel": "whatsapp",
  "status": "created",
  "external_ref": "customer_4821",
  "connection_id": null,
  "channel_id": null,
  "token_ready": false,
  "redirect_url": "https://app.example.com/connect/return",
  "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
  "last_error": null,
  "expires_at": "2026-10-31T15:00:00.000Z",
  "opened_at": null,
  "finished_at": null,
  "created_at": "2026-10-31T14:00:00.000Z"
}

ما الأخطاء التي قد يعيدها إنشاء جلسة؟

لكل خطأ الجسم نفسه، وهو كائن يحتوي على code وmessage، وتوضح الرسالة ما يجب إصلاحه. قد يعيد إنشاء الجلسة:

  • 400 invalid_json أو invalid_request: الجسم ليس كائن JSON، أو فشل حقل في التحقق، مثل redirect_url ليس من نوع https.
  • 400 channel_unavailable: القناة غير مفتوحة لهذا الحساب؛ وتسرد الرسالة القنوات المتاحة.
  • 401 unauthorized: مفتاح API مفقود أو غير صالح.
  • 402 billing_required: لا توجد بطاقة للحساب بعد، وكل ما يُتصل عبره يُحتسب عليها.
  • 429 cap_reached: هناك 50 جلسة مفتوحة بالفعل؛ انتظر حتى تنتهي أو تنتهي مدتها.
  • 429 rate_limited: أكثر من 100 جلسة في هذه الساعة؛ وتوضح الرسالة مدة الانتظار.

أين يصل العميل بعد ذلك؟

إلى redirect_url لديك، مع إضافة النتيجة إلى سلسلة الاستعلام. النتيجة نفسها موجودة في الجلسة، ويقرأها الخادم الخلفي عبر GET /connect-sessions/:id:

  • session: معرّف الجلسة، أي cs_ متبوعًا بأحرف عشوائية.
  • status: connected، أو cancelled عندما يختار العميل «Cancel and go back».
  • external_ref: معرّفك للعميل، عندما تحمله الجلسة.
  • connection_id: معرّف الرقم الجديد، لاستخدامه مع /connections.
  • channel_id: معرّف الحساب الاجتماعي الجديد، لاستخدامه مع /channels.
A number connected
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…

ما الحالات التي يمكن أن تكون عليها الجلسة؟

خمس حالات. يعرض GET /connect-sessions/:id الحالة الحالية، مع opened_at وfinished_at وlast_error، الذي يوضح سبب فشل آخر محاولة:

  • created: أنشأها خادمك الخلفي، ولم تُفتح بعد.
  • opened: حمّل العميل الصفحة المستضافة.
  • connected: اتصل رقم أو حساب اجتماعي، ومعرّفه موجود في الجلسة.
  • cancelled: غادر العميل عبر «Cancel and go back».
  • expired: انتهت الساعة قبل أن تكتمل الجلسة.

كم مدة عمل الرابط؟

ساعة واحدة من الإنشاء. بعدها تخبر الصفحة المستضافة العميل بانتهاء الرابط، مع زر للعودة إلى redirect_url لديك بالقيمة status=cancelled، وتصبح الجلسة منتهية. يمكن لحساب أن يفتح 50 جلسة وأن ينشئ 100 جلسة في الساعة، لأن Meta تحتسب كل تسجيل أولي ضمن حد على مستوى التطبيق يشترك فيه جميع الحسابات.

ماذا يفعل external_ref؟

يربط كل اتصال بعميلك. القيمة التي ترسلها تُحفظ على الرقم أو القناة التي تنشئها الجلسة، وتُضاف إلى إعادة التوجيه وتُدرج في كل حدث حالة يخصها، لذلك تسرد GET /connections?external_ref=customer_4821 وGET /channels?external_ref=customer_4821 ما اتصل به ذلك العميل. قد يجلب تسجيل الدخول عبر Facebook أو LinkedIn عدة صفحات دفعة واحدة: تسمّي إعادة التوجيه الأولى، ويسرد الفلتر البقية. استخدم معرّفًا ثابتًا من قاعدة بياناتك، لا بريدًا إلكترونيًا قد يتغير.

ماذا لو ألغى العميل أو فشل تسجيل الدخول؟

يتوقف ذلك على مكان الحدوث، وتحتفظ الجلسة بالسجل:

  • فشلت نافذة Meta المنبثقة أو أُغلقت: يضغط العميل Connect مجددًا في الصفحة نفسها ما دام الرابط مفتوحًا.
  • أُلغي تسجيل الدخول عبر شبكة اجتماعية أو رُفض: يعود العميل إلى الصفحة المستضافة مع السبب، ويمكنه المحاولة مرة أخرى حتى ينتهي الرابط.
  • الحساب متصل بالفعل عبر حساب easyCoexistence آخر: يوضح last_error ذلك، فيسجل العميل الدخول بحساب مختلف.
  • اختار العميل «Cancel and go back»: يتلقى redirect_url لديك القيمة status=cancelled وتُغلق الجلسة، لذا أنشئ جلسة جديدة لمحاولة أخرى.
  • انتهى الرابط: أنشئ جلسة جديدة.

ماذا لو اتصل رقم دون رمز العميل؟

تُنهي Meta أحيانًا Embedded Signup دون إصدار رمز الأعمال الخاص بالعميل. تطلب الصفحة المستضافة عندئذ خطوة إضافية واحدة، تستغرق بضع ثوانٍ. إذا تخطاها العميل، تظهر الجلسة كمتصلة مع token_ready بقيمة false، ويتلقى عنوان الأحداث لديك connection.token_missing: الرقم يستقبل الرسائل لأن معرّفاته صالحة، لكنه لا يستطيع الإرسال حتى تُنشأ جلسة اتصال جديدة تعيد ربطه وتصدر الرمز.

ماذا لو فشل webhook_url في فحص Meta؟

يتصل الرقم رغم ذلك. تفحص Meta webhook_url بطلب GET للتحقق، وتجتازه نقطتك إذا أعادت hub.challenge عند تطابق hub.verify_token. إذا فشل، يبدأ last_error في الجلسة بالعبارة webhook_url was not applied ويذكر سبب Meta، ويحدد PUT /connections/:id/webhook الوجهة بعد أن ترد نقطتك. وإذا عُيّنت خلال 24 ساعة من الاتصال، فإنها تظل تستقبل الاستيراد لمرة واحدة لجهات الاتصال، وسجل المحادثات إذا وافق العميل على مشاركته.

ماذا يرى العميل؟

صفحة على easycoexistence.com تعرض اسمك من partner_name، دون حساب أو بريد إلكتروني أو بطاقة يجب تعبئتها. بالنسبة لرقم WhatsApp، تعرض قائمة تحقق قصيرة للأهلية، ثم نافذة Meta المنبثقة ورمز QR لمسحه بتطبيق WhatsApp Business. أما الحساب الاجتماعي فتعرض زرًا واحدًا، مثل Continue with TikTok، يفتح شاشة الموافقة الخاصة بالشبكة في التبويب نفسه، فيعمل على الهواتف أيضًا.

الأخطاء الشائعة

  • الثقة بسلسلة الاستعلام وحدها. يستطيع أي شخص كتابة status=connected في رابط، لذا أكّد عبر GET /connect-sessions/:id من خادمك الخلفي قبل أن تسجّل العميل كمتصل.
  • تضمين الرابط في iframe. أرسل العميل إليه بإعادة توجيه أو في تبويب جديد، فهكذا صُممت الصفحة المستضافة وعمليات تسجيل الدخول التي تفتحها لتعمل.
  • إنشاء الروابط مسبقًا. يعمل كل رابط ساعة، وتُحتسب كل جلسة مفتوحة ضمن حد 50، لذا أنشئ الجلسة عندما يوشك العميل على الاتصال.
  • إرسال webhook_url أطول من 200 حرف. تقبل Meta عناوين رد الاتصال البديلة التي لا تتجاوز 200 حرف، فالأطول لا يُطبَّق ويتصل الرقم دونه.
إنجاز ذلك باستخدام EasyCoexistence

يربط easyCoexistence أرقام WhatsApp لعملائك وحسابات Instagram وFacebook وTikTok وYouTube وLinkedIn، وقنوات أخرى، ببرنامجك عبر رابط مستضاف واحد، ثم يمنح الخادم الخلفي لديك بيانات اعتماد كل اتصال وwebhook وأحداث الحالة الموقّعة. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع أول 3 أيام مجانية.

الأسئلة الشائعة

هل يمكن استخدام رابط الاتصال مرتين؟

لا. ينتهي الرابط برقم واحد، أو بتسجيل دخول اجتماعي واحد، وقد يجلب على Facebook أو LinkedIn عدة صفحات. بعد ذلك تصبح الجلسة متصلة، لذا أنشئ جلسة جديدة للاتصال التالي.

هل يمكنني إرسال الرابط عبر البريد الإلكتروني أو الدردشة؟

نعم، بشرط أن يفتحه العميل خلال الساعة. معرّف الجلسة في الرابط هو ما يخوّل الصفحة، لذا أرسل كل رابط إلى العميل الذي أُنشئ من أجله فقط.

هل تعمل الصفحة المستضافة على الهواتف؟

تعمل تسجيلات الدخول الاجتماعية، لأنها تُفتح في التبويب نفسه. ويُفضَّل ربط رقم WhatsApp من الحاسوب: على الهاتف تُفتح نافذة Meta المنبثقة في تبويب جديد، ويلزم الهاتف نفسه لمسح رمز QR.

كيف أعلم أن العميل اتصل دون استطلاع؟

اضبط عنوان أحداث الحالة في لوحة التحكم ضمن Profile ثم Developers. يرسل easyCoexistence بعدها connection.connected أو channel.connected، موقّعًا ويحمل external_ref لديك، فور اكتمال الاتصال.

تابع القراءة

Embedded Signup لعملائك على WhatsApp: تطبيق Tech Provider خاص بك أو صفحة مستضافةكيف تربط منصة SaaS أرقام WhatsApp Business لعملائها عبر Coexistence: ما تشترطه Meta من Tech Provider، وما تتحمله الصفحة المستضافة، وما يراه العملاء.مصادقة Partner API: مفاتيح Bearer ec_live_ والتدوير وأخطاء 401مصادقة طلبات Partner API: مفتاح ec_live_ واحد لكل حساب، يُنشأ من لوحة التحكم أو بأداة create_api_key، ويُعرض مرة واحدة، ويُدوَّر فورًا، وأخطاء 401 عند الفشل.حدود Partner API والقواعد: سياسات Meta و20 رسالة في الثانية وقاعدة الـ14 يومًاقواعد المنصة لقنوات عملائها: سياسات واتساب من Meta، و20 رسالة في الثانية لكل رقم Coexistence، وقاعدة 14 يومًا، وما يُنهي المفتاح.ربط رقم خطوة بخطوةتعرّف إلى ما يحدث عند ربط رقم عبر Coexistence، وما يفعله صاحب النشاط التجاري، وما يُحسم نهائياً ولا يمكن تغييره.ما الأرقام المؤهلة لـ Coexistenceإصدار التطبيق ونوع الحساب وصلاحية الوصول وما يجعل Meta ترفض الرقم أثناء إعداد Coexistence.واجهة برمجة التطبيقات (API) للشبكات الاجتماعية لوكلاء الذكاء الاصطناعي: النشر والجدولة والرد والقياسواجهة API وخادم MCP لوكلاء الذكاء الاصطناعي للنشر والجدولة والرد وقراءة التحليلات على الشبكات الاجتماعية، عبر واجهة كل شبكة الرسمية.

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

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

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

تم التحقق في