كيفية إضافة WhatsApp إلى SaaS باستخدام Embedded Signup و Coexistence
تضيف SaaS خدمة WhatsApp بربط رقم كل عميل الحالي عبر Embedded Signup مع Coexistence، فيبقى الرقم يعمل في تطبيق WhatsApp Business. ومع Partner API من easyCoexistence، تشغّل جلسة اتصال واحدة لكل عميل هذا التدفق في صفحة مستضافة، فتسلّم Meta رسائل الرقم إلى webhook_url الخاص بك، ويرد الخادم عبر Cloud API برمز الوصول (token) الخاص بالعميل نفسه.
معدل الإرسال الثابت لرقم يُستخدم مع تطبيق WhatsApp Business و Cloud API معاً.
أقدم إصدار من تطبيق WhatsApp Business يمكن ربط رقم العميل به عبر Coexistence.
المدى الزمني لسجل المحادثات الذي يمكن أن تشاركه Meta عند الإعداد، ويجب مزامنته خلال 24 ساعة.
نافذة خدمة العملاء في WhatsApp بعد رسالة المستخدم أو مكالمته، وكل رسالة جديدة تعيد ضبطها.
التاريخ الذي أوقفت فيه Meta الإصدارين v2 و v3 من Embedded Signup، ونُقلت التكاملات إلى v4.
ما مكونات تكامل WhatsApp؟
خمسة مكونات، ويتولى easyCoexistence الأول والأخير منها. يحتفظ منتجك بمنطق المحادثة وصندوق الوارد وما يكتبه نموذجك أو موظفو عملائك، بينما تنقل Meta الرسائل بين الرقم وخادمك:
ماذا يغيّر Coexistence لعملائك؟
يحتفظون برقمهم وهاتفهم. يبقى تطبيق WhatsApp Business يعمل إلى جانب Cloud API، فيرد الموظفون من الهاتف بينما يرد منتجك عبر API، وما يرسلونه من التطبيق يصل إلى خطاف الويب (webhook) الخاص بك بوصفه smb_message_echoes. ويترتب على ذلك ثلاثة قيود: يرسل الرقم بمعدل ثابت هو 20 رسالة في الثانية، ولا يستطيع غير API إرسال القوالب، وتفصل Meta الرقم إذا بقي الهاتف غير نشط نحو 14 يوماً.
كيف تبدو خطوة الربط في منتجك؟
يستدعي زر Connect WhatsApp من خادمك الطلب POST /connect-sessions مع redirect_url، ومعرّف عميلك بوصفه external_ref، وwebhook_url مع webhook_verify_token، فتوجّه Meta الرقم إليك منذ الدقيقة الأولى. يؤكد العميل قائمة قصيرة في الصفحة المستضافة، ثم يشغّل النافذة المنبثقة من Meta، ويمسح رمز QR بتطبيق WhatsApp Business، ويعود إليك مع connection_id. ويُنظر في دليل Embedded Signup فيما إذا كان الأفضل تشغيل Embedded Signup من تطبيق Tech Provider الخاص بك بدلاً من ذلك.
كيف تصل الرسائل إلى خادمك؟
من Meta مباشرة إلى webhook_url، دون أن تمر عبر easyCoexistence ودون نسخ محفوظ. يحمل حقل messages ما يرسله العملاء وحالة ما ترسله أنت، ويحمل smb_message_echoes ما يرسله الموظفون من التطبيق. توقّع Meta كل تسليم بالسر الخاص بتطبيق easyCoexistence (app secret)، وهو سر لا يُشارك أبداً، لذلك يكفي سر عشوائي طويل في مسار عنوان URL للتحقق منه. ويتشارك رقمان في حساب WhatsApp Business واحد وجهة واحدة، فوجّه بحسب value.metadata.phone_number_id.
كيف يرد خادمك ويرسل القوالب؟
عبر Graph API الخاص بـ Meta وبالـ token الخاص بالعميل من GET /connections/{id}?credentials=1، الذي يعيد أيضاً send_endpoint. يُرسَل النص الحر خلال 24 ساعة من آخر رسالة للشخص، وبعدها لا يُرسل إلا قالب وافقت عليه Meta:
- رد: POST /<
PHONE_NUMBER_ID>/messages مع type text، داخل النافذة. - قالب: الاستدعاء نفسه مع type template، واسم القالب ورمز لغته.
- إنشاء قالب: POST /<
WABA_ID>/message_templates، ثم استعلم عن حالته، لأن نتائج المراجعة لا تصل إلىwebhook_urlالخاص بك. - وسائط: POST /<
PHONE_NUMBER_ID>/media للرفع، وتصل الوسائط الواردة بمعرّف يُجلب بالـ token نفسه.
curl -X POST "$SEND_ENDPOINT" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511987654321",
"type": "text",
"text": { "body": "Your table for 4 is booked for 8 pm." }
}'هل يستطيع منتجك استيراد المحادثات الحالية للعميل؟
مرة واحدة، عند الربط. ومع ضبط webhook_url على الجلسة، يطلب easyCoexistence من Meta إرسال جهات اتصال الرقم، وإذا وافق العميل داخل التطبيق، تصل محادثات تصل إلى 180 يوماً عبر webhook من نوع smb_app_state_sync وhistory. تسمح Meta بذلك خلال 24 ساعة من الربط فقط، لذا اجعل نقطة النهاية (endpoint) تستجيب قبل إرسال الرابط. ويشرح دليل سجل المحادثات الحمولات.
من يدفع لـ Meta ثمن الرسائل؟
عميلك. تحتسب Meta الرسائل التي يرسلها خادمك عبر API على حساب WhatsApp Business الخاص بالعميل، بطريقة دفع يضيفها هناك، ولا يستطيع نشاط تجاري بلا طريقة دفع إرسال قوالب التسويق. ويحتسب easyCoexistence على حسابك رسوماً عن كل رقم متصل، ولا يحتسب أي رسوم على الرسائل ولا يضيف هامشاً على أسعار Meta.
ماذا يحدث عند انقطاع رقم؟
يستقبل عنوان أحداث منتجك connection.disconnected مع سبب Meta حين يكون معروفاً. وPRIMARY_INACTIVITY هو قاعدة الـ14 يوماً، وتعيد جلسة ربط جديدة لذلك العميل الرقم نفسه. أما connection.token_missing فيعني أن الرقم اتصل دون token الخاص بالعميل، فيستقبل الرسائل لكنه لا يستطيع الإرسال حتى تعيد جلسة جديدة ربطه.
الأخطاء الشائعة
- إرسال رابط الربط قبل أن تستجيب نقطة نهاية webhook لديك. يعمل استيراد السجل مرة واحدة فقط خلال 24 ساعة من الربط، والمحتوى الذي يُرسل قبل أن يعمل عنوانك يضيع.
- الرد بنص حر بعد إغلاق النافذة. فبعد مرور 24 ساعة على آخر رسالة للشخص، لا يمر إلا قالب معتمد.
- إطلاق حملة من رقم واحد بأقصى سرعة. فالرقم المتصل عبر Coexistence يرسل 20 رسالة في الثانية، لذا ضع إرسال كل رقم في طابور بهذا المعدل.
- توقّع أن يرسل الموظفون القوالب من الهاتف. ففي Coexistence يرسلها API وحده، لذا اجعل إرسال القوالب في منتجك.
يضيف easyCoexistence WhatsApp إلى SaaS الخاص بك عبر Embedded Signup من Meta وCoexistence في صفحة مستضافة تحمل اسمك. يحتفظ عملاؤك برقمهم وبتطبيق WhatsApp Business، وتسلّم Meta الرسائل إلى خادمك، وتصلك الأحداث موقّعة. وتربط الواجهة نفسها Instagram وFacebook وTikTok وYouTube وLinkedIn، وتنضم إليها قنوات أخرى. من US$ 9 إلى US$ 0.75 لكل اتصال في الشهر، ويقل السعر مع إضافة الاتصالات، والأيام الثلاثة الأولى مجانية.
الأسئلة الشائعة
هل يستطيع عميل ربط رقم موجود لدى مزود API آخر لـ WhatsApp؟
ليس وهو هناك. تطلب القائمة المستضافة رقماً لا يحمل أي مزود API آخر أو أداة أتمتة، لذا يفصله العميل عن ذلك المزود أولاً.
هل يستطيع SaaS الخاص بي إرسال قوالب WhatsApp لعملائه؟
نعم، عبر Cloud API بالـ token الخاص بكل عميل: أنشئ القالب في حساب WhatsApp Business الخاص بعميلك، وانتظر مراجعة Meta، ثم أرسله.
هل يقرأ easyCoexistence رسائل عملائي على WhatsApp؟
لا. تسلّم Meta رسائل الرقم مباشرة إلى webhook_url الذي تضبطه. والرقم الذي لا يملك webhook_url يعود إلى رد الاتصال الخاص بـ easyCoexistence، حيث تُسقط الرسائل دون حفظ.
كم يكلّف easyCoexistence لكل رقم WhatsApp؟
من US$ 9 إلى US$ 0.75 لكل رقم في الشهر، بحسب شريحة إجمالي اتصالاتك، مع أول 3 أيام مجانية. وتحتسب Meta رسوم الرسائل على حساب WhatsApp Business الخاص بكل عميل.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في