خطاف الويب (webhook) للمكالمات في WhatsApp: أحداث Calling API والمكالمات على رقم Coexistence
يُبلغ حقل المكالمات عن أحداث WhatsApp Business Calling API: الاتصال مع رد SDP أو عرضه، وحالات المكالمة RINGING وACCEPTED وREJECTED، والإنهاء مع COMPLETED أو FAILED والمدة، وcall_recording_available أو call_transcription_available. يذكر دليل Coexistence من Meta أن المكالمات الصوتية والمرئية لم تتغير في تطبيق WhatsApp Business، وأنها غير مدعومة في Cloud API، لذلك تبقى على الهاتف.
يربط easyCoexistence رقم تطبيق WhatsApp Business بواجهة Cloud API من Meta عبر Coexistence، فيرد الذكاء الاصطناعي والأتمتات على الرسائل وترسل القوالب، بينما تواصل المكالمات الرنين في التطبيق على هاتفك.
المكالمات الصوتية والمرئية في Cloud API لرقم تم تهيئته عبر تطبيق WhatsApp Business؛ وفي التطبيق تبقى كما هي.
الحد الأدنى اليومي للرسائل، بعدد المستلمين الفريدين، الذي يحتاجه الرقم قبل أن يستخدم Calling API.
المدة التي تبقى فيها تسجيلات المكالمات والنصوص المفرغة قابلة للتنزيل بعد تسليم webhook الخاص بها.
بادئة معرّفات المكالمات، وهي القيمة التي تربط خطافات الاتصال والحالة والإنهاء لكل مكالمة.
الإذن الذي يحتاجه التطبيق لاستقبال خطافات المكالمات، وهو نفسه المطلوب لخطافات الرسائل.
ماذا يُبلغ حقل المكالمات؟
كل ما يحدث لمكالمة تُجرى أو تُستقبل عبر Calling API، في حقل واحد يحمل حدثًا لكل مرحلة. تُنتج المكالمة التي يبدأها النشاط التجاري حدث اتصال connect، وتحديثات للحالة، وحدث إنهاء terminate. أما المكالمات المُدارة عبر SIP فتُبلغ call_created بدلًا من connect، دون جلسة SDP. ويوجد حدث مرتبط يقع في موضع آخر: عندما يرد العميل على طلب إذن المكالمة، يصل الرد عبر حقل messages ضمن رسالة تفاعلية من نوع call_permission_reply داخل حقل messages نفسه.
كيف يبدو خطاف المكالمات؟
الغلاف نفسه كأي خطاف webhook من WhatsApp، مع مصفوفة calls تحت value، وقيمة field تساوي calls. تحمل direction القيمة BUSINESS_INITIATED أو USER_INITIATED، وتحمل from وto أرقام الهواتف، وto_user_id معرّف BSUID للعميل، ويمكن أن يغيب أيٌّ من الرقمين لعميل يستخدم اسم مستخدم. يحدد metadata.phone_number_id رقمك، كما في أي حقل آخر. هذا مثال Call Connect الذي تنشره Meta، وقد أُبقيت العناصر النائبة كما هي:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315553601",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<CALLEE_NAME>",
"username": "<USERNAME>"
},
"wa_id": "16315553602",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
],
"calls": [
{
"id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"to": "16315553601",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "16315553602",
"event": "connect",
"timestamp": "1671644824",
"direction": "BUSINESS_INITIATED",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
]
},
"field": "calls"
}
]
}
]
}ما الحقول التي يضيفها حدث الإنهاء؟
terminate هو الحدث الذي تخزنه معظم الأنظمة، لأنه يغلق المكالمة. حقوله، بحسب مرجع Meta:
- status: COMPLETED عندما تنتهي المكالمة دون أخطاء غير متوقعة، بما فيها المكالمات التي لم يُرد عليها؛ وFAILED عندما لا تتصل أو تنقطع.
start_timeوend_timeوduration بالثواني: تظهر فقط عندما يرد الطرف الآخر.- errors: تحوي code وmessage وhref و
error_data.details، وذلك في المكالمات الفاشلة. biz_opaque_callback_data: سلسلة التتبع الخاصة بك، عندما مررت واحدة عند بدء المكالمة أو قبولها.
هل تعمل خطافات المكالمات على رقم Coexistence؟
يجيب دليل Coexistence من Meta عن ذلك في جدول الميزات: لا تتغير المكالمات الصوتية والمرئية في تطبيق WhatsApp Business، وهي غير مدعومة في Cloud API لرقم أُعدّ بهذه الطريقة. ويقول متطلبات Calling API المسبقة الأمر نفسه من الجهة الأخرى: يجب أن يكون رقم النشاط التجاري مستخدمًا مع Cloud API، لا مع تطبيق WhatsApp Business. لذا، على رقم Coexistence يواصل العملاء الاتصال كما في السابق، وترنّ المكالمة في التطبيق على الهاتف، ولا يوجد ما يُبلَّغ عنه في حقل المكالمات. أما النشاط الذي يحتاج المكالمات داخل البرمجيات فيستخدم رقمًا على Cloud API وحده.
كيف تتناسب أحداث المكالمة الواحدة معًا؟
بمعرّف المكالمة الذي يبدأ بـ wacid ويتكرر في كل حدث من أحداث تلك المكالمة. تُبلغ المكالمة التي يبدأها النشاط التجاري عن connect مع رد SDP، ثم الحالة RINGING ثم ACCEPTED أو REJECTED، وأخيرًا terminate. أما المكالمة التي يبدأها المستخدم فتُبلغ عن connect مع عرض SDP يردّ عليه نظامك، ثم terminate. أحداث التسجيل والنص المفرغ، عند تفعيلها، تأتي بعد terminate. خزّن الأحداث حسب id وevent، لأن إعادة المحاولة تكرر الأحداث ولا يُضمن ترتيب وصولها. وقائمة متطلبات Calling API الكاملة موجودة في الصفحة المتعلقة بالمكالمات على أرقام Coexistence، ضمن صفحات هذا الموقع.
ماذا يمكن للذكاء الاصطناعي أن يفعل بشأن المكالمات على رقم Coexistence؟
يعمل داخل المحادثة، بينما تبقى المكالمات مع الشخص على الهاتف. لا يشترك easyCoexistence في حقل المكالمات، ولا يملك أدوات مكالمات؛ يغطي موصّله وأتمتاته الرسائل والقوالب. عمليًا، يستطيع الرد الآلي أن يخبر العميل متى يكون أحد متاحًا للحديث وعلى أي رقم يتصل، وتستطيع أتمتة الكلمات المفتاحية أن ترد على «call» أو «phone» بهذه المعلومات، ويأخذ المالك المكالمة في تطبيق WhatsApp Business كما في السابق.
الأخطاء الشائعة
- الاشتراك في المكالمات لرقم Coexistence وانتظار الأحداث. تدرج Meta الاتصال بوصفه غير مدعوم في Cloud API لهذه الأرقام.
- توقّع start_time وduration في كل terminate. تظهر فقط عندما يُردّ على المكالمة؛ المكالمة التي لم يُرد عليها ما زالت تنتهي COMPLETED.
- البحث عن ردود الإذن في حقل المكالمات. تصل في حقل messages بوصفها رسائل تفاعلية من نوع call_permission_reply في حقل messages نفسه.
- ترك التسجيلات والنصوص المفرغة عند Meta. يمكن تنزيل كليهما لمدة 7 أيام بعد خطاف webhook الخاص بهما، ثم تختفيان.
تُراقب كل رقم على مدار الساعة، بما في ذلك قاعدة الـ14 يومًا التي تفصل الرقم الذي لا يُفتح تطبيقه. بدءًا من US$ 9 لكل رقم متصل شهريًا، وينخفض إلى US$ 0.75 مع إضافة الأرقام، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل يفقد العملاء زر الاتصال عندما يتصل رقم بالواجهة عبر Coexistence؟
يذكر دليل Coexistence من Meta أن المكالمات الصوتية والمرئية لم تتغير في تطبيق WhatsApp Business. يتصل العملاء بالرقم نفسه، ويرد المالك في التطبيق على هاتفه.
هل تُسعَّر Calling API مثل الرسائل؟
لا. تقول صفحة تسعير Meta إن Calling API له تسعير مختلف، وتشير إلى وثيقة تسعير منفصلة للمكالمات، لذلك لا تظهر رسوم المكالمات في كائن pricing ضمن حالات الرسائل.
هل يمكن تسجيل مكالمة من Calling API أو تفريغها نصيًا؟
نعم، عند تفعيل التسجيل أو التفريغ. بعد المكالمة ترسل Meta الحدث call_recording_available مع معرّف وسائط صوتي، أو call_transcription_available مع معرّف مستند JSON، عادةً خلال دقيقة.
هل يمكن أن يذهب خطاف المكالمات إلى نقطة نهاية مختلفة عن نقطة التطبيق؟
نعم. تسمح Meta بتوجيه حقل calls إلى عنوان URL بديل للاسترجاع، شأنه شأن حقل messages وحقول Coexistence الأخرى.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في