اربط كل قناة
في صندوق وارد واحد.

§ 00ما الذي ستحتاج إليه

كل قناة تستغرق 5–20 دقيقة للتوصيل. ستعمل في مكانين: لوحة المطوّر الخاصة بالقناة (BotFather لـ Telegram، Meta Developer Dashboard) وشاشة Channels داخل مساحة عمل EasyLiveChat الخاصة بك على app.livechattools.com/channels.

كل القنوات الأربع تشترك في نفس البنية داخل EasyLiveChat — محادثة موحّدة واحدة لكل جهة اتصال، صندوق وارد واحد، حقل ردّ واحد. الاختلافات في بيانات الاعتماد التي يطلبها كل مزوّد، وفي مخطط توقيع الـ webhook لديه.

§ 01Telegram

أبسط قناة في الإعداد. لا يحتاج Telegram إلى تطبيق مطوّر أو حساب أعمال — فقط بوت. توكنات البوت دائمة، والتكامل بأكمله يستغرق نحو خمس دقائق.

1. أنشئ بوتاً عبر BotFather

افتح Telegram وابدأ محادثة مع @BotFather. أرسل /newbot، اختر اسم عرض واسم مستخدم ينتهي بـ bot. يرد BotFather بتوكن بهذا الشكل 1234567890:ABCdefGHI…. انسخه.

2. اربطه في EasyLiveChat

في مساحة عملك انتقل إلى Channels → Telegram Bot → Connect. الصق توكن البوت. اختر أي اسم عرض — يظهر فقط داخل صندوق الوارد. أرسل.

افتح Integration settings على الصف الذي أُنشئ حديثاً لإظهار Webhook secret وعنوان callback الخاص بالتكامل.

3. وجِّه Telegram إلى webhook الخاص بنا

لا تملك Telegram Bot API واجهة لإعداد webhooks؛ تُضبط عبر setWebhook. استبدل البدائل أدناه بتوكن البوت ومعرّف التكامل وسرّ الـ webhook، ثم نفّذه مرة واحدة:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.livechattools.com/api/channels/webhook/telegram/${INTEGRATION_ID}",
    "secret_token": "${WEBHOOK_SECRET}",
    "allowed_updates": ["message", "edited_message"]
  }'

يرد Telegram بـ {"ok":true,"description":"Webhook was set"}. . تحقّق عبر getWebhookInfo — — وينبغي أن تنخفض قيمة pending_update_count إلى 0.

4. اختبر

افتح t.me/yourbot_username في Telegram، اضغط Start، أرسل أي رسالة. يجب أن تظهر في صندوق وارد EasyLiveChat خلال أقل من ثانية مع اسم المرسل ورمز اللغة. ردّ من اللوحة — سيصل على Telegram الخاص بالزائر بعد لحظات.

§ 02WhatsApp Cloud

Meta Cloud API هو الخيار المناسب لمعظم الناس — مُستضاف بالكامل، مجاني حتى 1000 محادثة خدمة شهرياً، والناقل الوحيد لـ WhatsApp الذي لا يحتاج أي بنية تحتية لديك. الإعداد أثقل من Telegram لأن Meta تتطلب تطبيق مطوّر وحساب أعمال موثّقاً لحركة الإنتاج.

1. أنشئ تطبيق مطوّر في Meta

اذهب إلى developers.facebook.com/apps → Create App. اختر اسماً وبريداً، ثم في الشاشة التالية اختر حالة الاستخدام “Connect with customers through WhatsApp”. اربط Business Portfolio — قائماً أو Test Business المدمج للتقييم.

بعد إنشاء التطبيق، افتح Use Cases → Connect on WhatsApp → API Setup. سترى Phone Number ID (الرقم التجريبي المجاني من Meta، أو رقمك بعد إضافته) وزر Generate access token. اضغطه، وافق، وانسخ التوكن الناتج. انسخ Phone Number ID أيضاً.

2. احصل على App Secret

في لوحة Meta نفسها، افتح App settings → Basic. App Secret مخفي خلف زر Show — أظهره وانسخه. هذا مفتاح HMAC الذي تستخدمه Meta لتوقيع كل POST لـ webhook. بدونه سيتم رفض رسائلك الواردة بـ BAD_SIGNATURE.

3. اربط WhatsApp في EasyLiveChat

Channels → WhatsApp Cloud → Connect. أدخل اسم العرض (حرّ)، Phone Number ID، Access Token، وApp Secret. أرسل. افتح إعدادات التكامل لنسخ webhook secret المُنشأ تلقائياً ومعرّف التكامل.

4. اضبط webhook الخاص بـ Meta

عُد إلى لوحة Meta، اذهب إلى Use Cases → Connect on WhatsApp → Configuration. الصق:

Callback URL : https://api.livechattools.com/api/channels/webhook/whatsapp/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

اضغط Verify and save. ترسل Meta مصافحة GET — ونردّ بتحديها إذا تطابق verify token. على نفس الصفحة، ابحث عن قائمة Webhook fields وفعّل messages إلى Subscribed. بدون هذا التفعيل، تقبل Meta عنوان webhook لكنها لا تُسلّم إليه شيئاً أبداً.

5. أضف مستلِم اختبار (Sandbox فقط)

إذا كنت تستخدم رقم Meta التجريبي المجاني، يجب إضافة كل مستلِم إلى قائمة السماح قبل أن ترسل إليه. في API Setup → To، أضف رقم الهاتف الذي ستراسله — ترسل Meta رمز OTP من 6 أرقام للتحقق. يمكنك إضافة حتى خمسة مستلمين تجريبيين. أرقام الأعمال الحقيقية لا تخضع لهذا القيد.

§ 03Facebook Messenger

يستخدم Messenger نفس تطبيق Meta وApp Secret وسباكة webhook التي يستخدمها WhatsApp — لكنه يتحدث إلى Facebook Page بدلاً من رقم هاتف، وتوكنات الوصول هي Page Access Tokens، وليست توكنات WhatsApp Business.

1. أضف Messenger إلى تطبيق Meta

في التطبيق نفسه الذي استخدمته لـ WhatsApp (أو واحد جديد)، افتح Use cases → Add use cases → فلتر Business messaging → Engage with customers on Messenger from Meta. احفظ. يحتوي التطبيق الآن على منتجَين جنباً إلى جنب.

2. اربط صفحة Facebook

افتح Messenger from Meta → Messenger API Settings. تحت Generate access tokens، اضغط Connect بجانب No FB pages yet. تسأل Meta أيّ الصفحات تمنحها الوصول — اختر التي تريد تلقّي الرسائل عليها، وافق على الأذونات، احفظ.

تظهر الصفحة الآن مع Page Access Token بنقرة واحدة وPage ID. انسخ كليهما. Page ID هو أيضاً القيمة التي تلصقها بـ pageId في EasyLiveChat.

3. اربط Messenger في EasyLiveChat

Channels → Messenger → Connect. املأ Page ID وPage Access Token وApp Secret نفسه الذي استخدمته لـ WhatsApp. أرسل وانسخ webhook secret ومعرّف التكامل الجديد.

4. اشتراك webhook بطبقتين

في Messenger خصوصية لا توجد في WhatsApp: يحتاج اشتراكين ليُسلّم أي شيء. أولاً الاشتراك على مستوى التطبيق — في Messenger API Settings → Configure webhooks الصق:

Callback URL : https://api.livechattools.com/api/channels/webhook/messenger/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

اضغط Verify and save، ثم وسّع Webhook fields وفعّل messages. بعدها الاشتراك على مستوى الصفحة، الذي لا يمكن إنجازه من الواجهة — نفّذ هذا curl:

curl -X POST "https://graph.facebook.com/v20.0/${PAGE_ID}/subscribed_apps" \
  -d "subscribed_fields=messages,messaging_postbacks,message_deliveries,message_reads" \
  -d "access_token=${PAGE_ACCESS_TOKEN}"

بدون الاشتراك على مستوى الصفحة، ترجع Meta {"success":true} على اشتراك التطبيق لكنها لا تُطلق webhook فعلياً. تأكّد من توصيل كل شيء عبر الاستعلام:

curl "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions?access_token=${APP_ID}|${APP_SECRET}"

ينبغي أن يدرج الرد كائناً من نوع page مع fields غير فارغة تتضمن messages.

§ 04Instagram DM

تجري مراسلة Instagram عبر نفس أنابيب Messenger Platform، لكنها تضيف متطلبَين: يجب أن يكون حساب Instagram حساب أعمال (لا شخصياً ولا Creator)، ويجب أن يكون مرتبطاً بصفحة Facebook ضمن نفس Business Portfolio. عندما يتحقق كلاهما، يصبح Page Access Token هو نفسه توكن وصول Instagram.

1. حوّل حساب IG إلى Business

على تطبيق Instagram للموبايل: Settings → Account → Switch to professional account → Business. اختر أي فئة. التحويل قابل للعكس.

2. أضف حساب IG إلى Business Portfolio

في Meta Business Suite Settings → Accounts → Instagram accounts → Add → سجّل الدخول ببيانات IG. تؤكد Meta وتعرض Instagram Business Account ID — رقم من 17 خانة يبدأ بـ 1784…. انسخه؛ هذا هو pageId لتكامل EasyLiveChat.

3. اربط IG بصفحة Facebook

هذه الخطوة الأكثر إغفالاً. افتح Inbox الخاص بصفحة Facebook في Meta Business Suite — business.facebook.com/latest/inbox?asset_id={page_id}. تظهر لافتة “Connect to Instagram” مع زر Connect. اضغطه، سجّل الدخول إلى Instagram، امنح الأذونات المطلوبة، أكّد. بعد ذلك ستبدأ Graph API من Meta بالإجابة على الاستفسارات حول حساب IG ضمن نطاق توكن وصول الصفحة.

4. اربط Instagram في EasyLiveChat

Channels → Instagram DM → Connect. استخدم IG Business Account ID من الخطوة 2 كـ pageId، ونفس Page Access Token الذي استخدمته لـ Messenger كـ pageAccessToken، ونفس App Secret كما سابقاً.

5. اشترك على الطبقتين

يستخدم Instagram object=instagram لـ webhooks على مستوى التطبيق (استخدم Messenger object=page. ). أضف curl هذا فوق اشتراك Messenger الموجود لديك:

curl -X POST "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions" \
  -d "object=instagram" \
  -d "callback_url=https://api.livechattools.com/api/channels/webhook/instagram/${INTEGRATION_ID}" \
  -d "verify_token=${WEBHOOK_SECRET}" \
  -d "fields=messages,messaging_postbacks,message_reactions" \
  -d "access_token=${APP_ID}|${APP_SECRET}"

§ 05حلّ المشكلات