تسجيل الدخولابدأ الفترة التجريبية المجانية
Meta Tech Provider

خطاف الويب (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، فيرد الذكاء الاصطناعي والأتمتات على الرسائل وترسل القوالب، بينما تواصل المكالمات الرنين في التطبيق على هاتفك.

Not supported

المكالمات الصوتية والمرئية في Cloud API لرقم تم تهيئته عبر تطبيق WhatsApp Business؛ وفي التطبيق تبقى كما هي.

2,000

الحد الأدنى اليومي للرسائل، بعدد المستلمين الفريدين، الذي يحتاجه الرقم قبل أن يستخدم Calling API.

7 days

المدة التي تبقى فيها تسجيلات المكالمات والنصوص المفرغة قابلة للتنزيل بعد تسليم webhook الخاص بها.

wacid

بادئة معرّفات المكالمات، وهي القيمة التي تربط خطافات الاتصال والحالة والإنهاء لكل مكالمة.

whatsapp_business_messaging

الإذن الذي يحتاجه التطبيق لاستقبال خطافات المكالمات، وهو نفسه المطلوب لخطافات الرسائل.

ماذا يُبلغ حقل المكالمات؟

كل ما يحدث لمكالمة تُجرى أو تُستقبل عبر Calling API، في حقل واحد يحمل حدثًا لكل مرحلة. تُنتج المكالمة التي يبدأها النشاط التجاري حدث اتصال connect، وتحديثات للحالة، وحدث إنهاء terminate. أما المكالمات المُدارة عبر SIP فتُبلغ call_created بدلًا من connect، دون جلسة SDP. ويوجد حدث مرتبط يقع في موضع آخر: عندما يرد العميل على طلب إذن المكالمة، يصل الرد عبر حقل messages ضمن رسالة تفاعلية من نوع call_permission_reply داخل حقل messages نفسه.

connectThe call is ready to connect; session carries the SDP to apply to your WebRTC stack.
call_createdA SIP call was attempted, business- or user-initiated.
statuses (type call)RINGING, ACCEPTED or REJECTED for a business-initiated call.
terminateThe call ended: status COMPLETED or FAILED, with times and duration when answered.
call_recording_availableA media id for the finished audio recording.
call_transcription_availableA media id for the transcript, a JSON document.

كيف يبدو خطاف المكالمات؟

الغلاف نفسه كأي خطاف webhook من WhatsApp، مع مصفوفة calls تحت value، وقيمة field تساوي calls. تحمل direction القيمة BUSINESS_INITIATED أو USER_INITIATED، وتحمل from وto أرقام الهواتف، وto_user_id معرّف BSUID للعميل، ويمكن أن يغيب أيٌّ من الرقمين لعميل يستخدم اسم مستخدم. يحدد metadata.phone_number_id رقمك، كما في أي حقل آخر. هذا مثال Call Connect الذي تنشره Meta، وقد أُبقيت العناصر النائبة كما هي:

Meta's example: the Call Connect webhook
{
  "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 الخاص بهما، ثم تختفيان.
إنجاز ذلك باستخدام EasyCoexistence

تُراقب كل رقم على مدار الساعة، بما في ذلك قاعدة الـ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 Business على رقم Coexistenceتبقى مكالمات الصوت والفيديو تعمل في تطبيق WhatsApp Business بعد Coexistence، لكن Calling API لا يدعم هذه الأرقام. إليك ما يعنيه ذلك لك.حالات خطاف الويب (webhook) في WhatsApp: مرسلة ومسلمة ومقروءة وفاشلةكيف يبلغ WhatsApp بما حدث لرسالة أرسلتها: مصفوفة statuses، وقيمة كل حالة، والحقول، والمطابقة عبر wamid وبيانات Meta الفعلية.ما ميزات WhatsApp التي تتوقف بعد Coexistence؟تتوقف الرسائل المختفية، والعرض لمرة واحدة، والموقع المباشر، وقوائم البث على الرقم المتصل. إليك معنى ذلك عمليًا.ما الذي يتزامن مع API وما الذي لا يتزامنتنتقل جهات الاتصال وسجل المحادثات الفردية، بينما لا تنتقل المجموعات والكتالوج والتصنيفات والردود السريعة والرسائل التلقائية.نقل رقم من Coexistence إلى Cloud API فقطإخراج رقم من تطبيق WhatsApp Business وتشغيله على Cloud API وحده: ترتيب الخطوات، والسجل الذي تقول Meta إنه يُفقد، وما الذي يتغير.إعادة محاولات webhook في WhatsApp والتكرار والترتيب: كيفية التعامل معهايعيد Meta إرسال webhooks في WhatsApp لمدة تصل إلى 7 أيام، لذا التكرار أمر طبيعي والترتيب غير مضمون. مفاتيح إزالة التكرار، ومعالج آمن، وما يجب إرجاعه.

هل أنت مستعد للبدء؟

أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.

ابدأ الفترة التجريبية المجانية

تم التحقق في