واجهة Call البرمجية وWebhooks للمطورين: المفاتيح والنطاقات والأحداث
جولة عملية في واجهة REST البرمجية لـ Call: مفاتيح API ونطاقاتها، وحدود المعدل، ومعالجة الأخطاء، وWebhooks الموقّعة، وصفحة «المطورون» لإدارة نقاط النهاية.
عاجلًا أو آجلًا يحتاج نظام الهاتف إلى التخاطب مع شيء آخر: نظام CRM ينبغي أن يعرض المكالمة فور انتهائها، أو أداة فوترة تريد معرفة من اتصل، أو برنامج نصي يجري مكالمة حين يُرسل نموذج. ولدى Call واجهة REST برمجية وWebhooks صادرة لهذا الغرض تحديدًا. يشرح هذا الدليل كيف تتكامل القطع، وما الذي تطلبه قبل كتابة الشيفرة، والأخطاء التي تكلّف المطور غالبًا فترة ما بعد الظهر.

إذا كان هدفك ببساطة نقل جهات الاتصال دفعة واحدة، فاقرأ أولًا استيراد جهات الاتصال إلى نظام CRM لفريق الهاتف؛ فالاستيراد غالبًا أسهل من التكامل.
من أين تبدأ: المرجع وصفحة «المطورون»
هناك مكانان ينبغي أن تعرفهما. «مرجع API» موجود ضمن «الإعدادات»، وأيضًا في قائمة «الموارد» في الصفحة الرئيسية. ويمكن قراءته دون تسجيل الدخول، وهذا مفيد حين تحدد نطاق عمل لعميل. أما صفحة «المطورون»، الموجودة أيضًا ضمن «الإعدادات»، فهي لمساحة عملك: تعرض معرّفي منشأتك ووكيلك، ونقاط نهاية Webhooks لديك، وقائمة مفاتيحك للقراءة فقط.
ما الذي يقدمه كل مكان
- «ابدأ من هنا»عنوان URL الأساسي والأعراف، والمصادقة مع جدول النطاقات، والأخطاء مع رموز الحالة.
- «نقاط النهاية»تسرد بطاقة كل نقطة نهاية نطاقها ومعاملاتها ومتن الطلب والاستجابة والأخطاء، مع طلبات جاهزة للنسخ بـ curl وJavaScript وPython.
- «بحث»اضغط / للانتقال إلى البحث في نقاط النهاية والتصفية حسب الأسلوب أو المسار أو النطاق أو الملخص.
- «OpenAPI JSON»ينزّل المواصفات كاملة في ملف واحد لأدواتك الخاصة.
- «معرّف الوكيل / API»معرّف منشأتك واسمها المختصر، ووضع API (بيئة تجريبية أو مباشر)، ومعرّف وكيل الذكاء الاصطناعي الذي تختاره، ولكل منها زر «نسخ».
- «Webhooks»نقاط النهاية لديك، والأحداث التي تستقبلها كل منها، وآخر حالة HTTP، وأي عمليات تسليم فاشلة.
اقرأ أقسام حدود المعدل وWebhooks الصادرة قبل الإطلاق، لا بعده. فهي تصف سلوكًا يسهل إغفاله في اختبار سريع.
مفاتيح API والنطاقات
يحمل كل طلب مفتاحًا في ترويسة Authorization بوصفه رمز bearer. ولا تُنشأ المفاتيح في التطبيق: بل يصدرها مشغّل مساحة عملك ويخبرك بالنطاقات التي تحملها. ويُعرض المفتاح كاملًا مرة واحدة لحظة إصداره، ثم لا تظهر بعد ذلك إلا أحرفه الأولى، فاحفظه في مخزن الأسرار لديك فورًا.
| النطاق | ما يسمح به |
|---|---|
| read | قراءة جهات الاتصال والمكالمات وقوائم الانتظار وأعضاء الفريق والتقارير وقائمة عدم الاتصال. |
| write | إنشاء جهات الاتصال وتحديثها، وتسجيل نتائج المكالمات، وإضافة أرقام إلى قائمة عدم الاتصال. |
| calls | إجراء المكالمات وإنهاؤها. |
| admin | إدارة Webhooks؛ ويمكنه أيضًا استدعاء كل نقاط النهاية الأخرى. |
اطلب أصغر مجموعة تؤدي المهمة. فبرنامج التقارير يحتاج إلى read ولا شيء غيره؛ وزر النقر للاتصال يحتاج إلى calls. وإذا أعاد الطلب 403 مع الرمز insufficient_scope، فالمفتاح يفتقر إلى النطاق المذكور في بطاقة نقطة النهاية تلك.
البيئة التجريبية والبيئة المباشرة
يمكن إصدار المفاتيح لبيئة تجريبية تستخدم محاكيًا ولا تجري مكالمات حقيقية، أو للاستخدام المباشر. تعامل مع بادئة المفتاح على أنها مجرد تسمية: فالمفتاح الموسوم بأنه للاختبار يعمل على البيانات نفسها واتصال الهاتف نفسه الذي يعمل عليه المفتاح المباشر، فلا تعتمد على البادئة لإبعاد التجارب عن العملاء الحقيقيين. واستخدم وضع API المعروض في صفحة «المطورون» لتعرف أين تقف.
إجراء المكالمات عبر الواجهة البرمجية
تغطي نقاط النهاية العامة الأساسيات: فحص السلامة، وسرد المكالمات، وقراءة مكالمة واحدة، وإجراء مكالمة، وإنهاؤها، وإدارة Webhooks، والمحادثة مع وكيل ذكاء اصطناعي. والمكالمة الصادرة المُجراة عبر الواجهة البرمجية تمر بفحص الامتثال نفسه الذي تمر به المكالمة من المكتب، فيُرفض الرقم المدرج في قائمة عدم الاتصال أو خارج ساعات الاتصال المسموح بها، تمامًا كما يُرفض للموظف. ابنِ شيفرتك لتعامل هذا الرفض على أنه نتيجة عادية لا خلل.
وهذا مهم للتصميم. لا تكتب حلقة تعيد محاولة المكالمة المرفوضة حتى تنجح. اقرأ السبب، وسجّله، وامضِ قدمًا. ولمعرفة القواعد التي تقف وراء هذا الرفض، راجِع حارس ساعات الاتصال في Call و قائمة عدم الاتصال في Call.
حدود المعدل والأخطاء
لكل مفتاح حده الخاص من الطلبات في الدقيقة، يُحدد عند إصدار المفتاح؛ والقيمة الافتراضية 120. وحين يستنفد المفتاح حصة الدقيقة، تجيب الواجهة البرمجية بـ 429 مع الرمز rate_limited وتخبرك بمدة الانتظار في الترويسة X-RateLimit-Reset. انتظر تلك المدة ثم تابِع. والعميل البرمجي المهذب يبطئ نفسه قبل أن يصطدم بالجدار.
- 429 rate_limited: تراجع طوال المدة المذكورة في ترويسة إعادة الضبط، ووزّع العمل الكبير على فترة زمنية.
- 403 insufficient_scope: المفتاح يفتقر إلى النطاق المذكور في بطاقة نقطة النهاية؛ اطلب مفتاحًا يتضمنه.
- أخطاء أخرى: تصرّف بناءً على رمز الخطأ لا على رسالته. فالرموز لا تتغير؛ أما الصياغة فقد تتغير.
معالجة طلب فاشل
- اقرأ الحالةهل هو خطأ من جهة العميل يمكنك إصلاحه، أم خطأ في الخادم تستحق إعادة المحاولة؟
- اقرأ الرمزافرّع منطقك حسب الرمز، لا حسب نص الرسالة أبدًا.
- تراجعفي حالة 429، انتظر ترويسة إعادة الضبط؛ وفي أخطاء الخادم، أعِد المحاولة بضع مرات بفواصل متزايدة.
- سجّل التفاصيلاحتفظ بنقطة النهاية والرمز والوقت ليتمكن الدعم من تتبعها.
- توقف عند الرفضرفض الامتثال قرار لا عطل؛ فلا تدخل في حلقة بشأنه.
Webhooks: استقبال الأحداث
بدلًا من سؤال الواجهة البرمجية مرارًا وتكرارًا عما إذا كان شيء قد حدث، دع Call يخبرك. في صفحة «المطورون»، اضغط «إضافة نقطة نهاية»، وأدخل عنوان https عامًا، وحدد الأحداث التي تريدها؛ وعدم تحديد أي حدث يعني جميع الأحداث. ويُعرض مفتاح التوقيع السري مرة واحدة، عند إضافة نقطة النهاية. فانسخه حينها. وإذا فُقد، فاحذف نقطة النهاية وأضفها من جديد للحصول على مفتاح جديد.
كل عملية تسليم موقّعة. تحمل ترويسة التوقيع قيمة HMAC-SHA256 للطابع الزمني والمتن مفصولين بنقطة، محسوبة بمفتاح التوقيع السري، وتحمل ترويسة منفصلة الطابع الزمني. أعِد حسابها من جهتك وقارنها قبل أن تثق بالحمولة. ويتضمن «مرجع API» شيفرة نموذجية لذلك بـ Node.js وPython، ورفض الطوابع الزمنية القديمة يحميك من الطلبات المعادة.
مستقبِل Webhook جيد وآخر رديء
| جيد | رديء | |
|---|---|---|
| التوقيع | يُتحقق منه في كل طلب | يُوثق به دون تحقق |
| الرد | 2xx خلال ثوانٍ، مع جدولة العمل لاحقًا | معالجة بطيئة قبل الرد |
| التكرارات | استقبال الحدث نفسه مرتين آمن | يُنشئ سجلين |
| الإخفاقات | ينبّه حين تفشل عمليات التسليم | صامت حتى يلاحظ أحد |
يجب أن تجيب نقطة النهاية لديك بحالة 2xx خلال 10 ثوانٍ. ويُعاد إرسال التسليم الفاشل، حتى ست محاولات إجمالًا، وتُعطّل نقطة النهاية التي تفشل 50 مرة متتالية. ويعرض كل صف في صفحة «المطورون» آخر حالة HTTP وعدد عمليات التسليم الفاشلة، ويُطلق «إرسال اختبار» حدث اختبار موقّعًا واحدًا لترى ما يجيب به خادمك.
قائمة تحقق قبل الإطلاق
قبل أن تفعّل التكامل
- تعرف النطاقات التي يحملها المفتاح، وليس فيها أكثر من الحاجة
- المفتاح محفوظ في مخزن أسرار، لا في الشيفرة المصدرية
- يُتحقق من توقيعات Webhook وتُرفض الطوابع الزمنية القديمة
- المستقبِل يجيب بسرعة ويتعامل مع الأحداث المكررة
- تُعالج استجابات حد المعدل والرفض دون حلقات إعادة محاولة متلاحقة
- اختبرت في وضع البيئة التجريبية وضغطت «إرسال اختبار» على نقطة النهاية
- هناك شخص مسمّى يتلقى تنبيهًا إذا بدأت عمليات التسليم تفشل
التطبيق في Call
في Call، افتح «الإعدادات» ثم «مرجع API» لدراسة نقاط النهاية، و«الإعدادات» ثم «المطورون» لنسخ معرّف منشأتك والتحقق من مفاتيحك وإضافة Webhook. يستطيع المالكون والمسؤولون والمديرون إضافة نقاط النهاية واختبارها وحذفها؛ ويرى الآخرون القائمة فقط. وإذا كنت تستخدم أيضًا ميزات وكيل الذكاء الاصطناعي، فإن معرّف الوكيل في الصفحة نفسها يغذي نقطة نهاية المحادثة. وللجانب الصوتي من المنتج، راجِع إعداد وكيل ذكاء اصطناعي في Call.
الأسئلة الشائعة
كيف أحصل على مفتاح API؟
يصدر المفاتيحَ مشغّلُ مساحة عملك؛ ولا يمكن إنشاؤها في التطبيق. اطلب مفتاحًا واذكر النطاقات التي يحتاجها. ويُعرض المفتاح كاملًا مرة واحدة عند إصداره.
ماذا تعني الاستجابة 429؟
استنفد المفتاح طلباته للدقيقة الحالية. انتظر عدد الثواني المذكور في الترويسة X-RateLimit-Reset، ثم حاول مجددًا، ووزّع العمل الكبير على فترة أطول.
كيف أتحقق من أن Webhook جاء فعلًا من Call؟
احسب قيمة HMAC-SHA256 للطابع الزمني والمتن بمفتاح التوقيع السري، وقارنها بترويسة التوقيع. ويعرض «مرجع API» أمثلة بـ Node.js وPython.
هل يمكنني إرسال Webhooks إلى خادم تطوير محلي؟
ليس مباشرة. يجب أن تكون نقاط النهاية عناوين https عامة، فاستخدم أداة نفق تكشف خادمك المحلي عبر عنوان منها.
لماذا رُفض طلبي لإجراء مكالمة عبر الواجهة البرمجية؟
المكالمات المُجراة عبر الواجهة البرمجية تمر بفحص الامتثال نفسه الذي تمر به مكالمات المكتب. فيُرفض الرقم المدرج في قائمة عدم الاتصال أو خارج ساعات الاتصال.
من يستطيع رؤية Webhooks وتغييرها؟
يستطيع الجميع قراءة القائمة، لكن لا يستطيع إضافة نقاط النهاية أو اختبارها أو حذفها إلا المالكون والمسؤولون والمديرون.