> For the complete documentation index, see [llms.txt](https://library.zoom.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://library.zoom.com/technical-library/technical-library-ar/khdmat-alaamal/zoom-contact-center/expert-insights/integrate-engagement-data.md).
# دمج بيانات التفاعل
بقلم Justin Steinberg
### نظرة عامة
ينشئ Zoom مركز الاتصال بيانات قيّمة حول التفاعل أثناء كل تفاعل مع العميل، بما في ذلك تسجيلات المكالمات، والنسخ، وملاحظات الوكيل، ونتائج التفاعل. تابع القراءة لمعرفة كيفية تخزين بيانات التفاعل في أنظمة خارجية (مثل CRM وأنظمة السجلات الأخرى) لإنشاء عرض موحّد للعميل، وتمكين تدريب فعّال للوكلاء، أو تلبية متطلبات الامتثال عند استخدام Zoom مركز الاتصال.
سنستعرض طرق التكامل المختلفة لمساعدتك على اختيار النهج الأفضل استنادًا إلى كيفية تمكّن وكلائك من العمل بكفاءة أكبر.
تعتمد الطريقة الأفضل بشكل أساسي على عامل رئيسي واحد: **التطبيق الذي يتعامل فيه الوكلاء مع تفاعلاتهم**۔ الخياران اللذان سنناقشهما هما:
1. الوكلاء الذين يستخدمون موصل ZCC CRM CTI الجاهز ضمن CRM.
2. الوكلاء الذين يعملون في تطبيق Zoom Workplace، والذي يتطلب حلاً مخصصًا باستخدام واجهات برمجة التطبيقات وخطافات الويب الخاصة بـ ZCC.
***
### تكامل موصل CRM CTI الجاهز
هذه هي الطريقة الأكثر مباشرة. إذا كان وكلاؤك يستخدمون موصل ZCC CRM CTI، فيمكن مزامنة معظم بيانات التفاعل تلقائيًا بين منصة Zoom وCRM المناسب.
#### كيف يعمل
يضمّن موصل CTI واجهة وكيل ZCC مباشرةً في CRM. عند انتهاء التفاعل، تُحفظ بيانات مثل التسجيلات والنسخ والملاحظات ونتائج التفاعل تلقائيًا داخل Zoom، وتُربط بالسجل ذي الصلة (مثل تذكرة أو جهة الاتصال) في CRM لديك.
#### متطلبات الإعداد
تتوفر الوظيفة التي تسمح بمزامنة البيانات بين Zoom وCRM بشكل جاهز، لكنها تتطلب التفعيل ضمن بوابة المسؤول في ZCC.
أكمل الخطوات التالية:
{% stepper %}
{% step %}
**تمكين في بوابة المسؤول في ZCC**
سجّل الدخول إلى بوابة المسؤول في Zoom بصفتك مسؤولاً. في [مركز المسؤول](https://zoom.com/account)، انتقل إلى إدارة CX ← مركز الاتصال ← عمليات التكامل ← [التطبيقات](https://zoom.com/cci/index/admin#/admin-integrations).
اعثر على تكامل CRM ذي الصلة ومكّن الإعدادات المناسبة للسماح بتخزين البيانات في CRM لديك.
{% endstep %}
{% step %}
**أذونات CRM**
راجع واتبع [أدلة إعداد تكامل CRM](https://support.zoom.com/) للتحقق من أن مستخدم تكامل CRM لديك يمتلك أذونات الكتابة اللازمة لجميع الكائنات ذات الصلة.
{% endstep %}
{% endstepper %}
#### منصات CRM المدعومة
يمكن الوصول إلى هذه الوظيفة من خلال موصل ZCC CRM CTI عندما يستخدم الوكلاء أنظمة CRM التالية:
* سيلزفورس
* Zendesk
* ServiceNow
* Microsoft Dynamics
* HubSpot
مع موصلات CRM CTI، لا يلزم إجراء تكوين خاص، وسيحفظ التكامل بيانات التفاعل في CRM بشكل افتراضي.
***
### تكامل مخصص عبر واجهات برمجة التطبيقات
إذا كان وكلاؤك يستخدمون تطبيق Zoom Workplace الأصلي أو ZCC Smart Embed، فستحتاج إلى حل مخصص لنقل بيانات التفاعل. والطريقة الأساسية للقيام بذلك هي باستخدام واجهات برمجة التطبيقات الخاصة بـ Zoom مركز الاتصال.
هناك نهجان رئيسيان للوصول إلى بيانات التفاعل عبر واجهة برمجة التطبيقات:
* **الاستعلام الدوري:** استعلم دوريًا عن واجهة برمجة التطبيقات الخاصة بـ Zoom لمعرفة ما إذا كانت بيانات تفاعل جديدة متاحة.
* **خطافات الويب:** تلقي إشعارًا في الوقت الفعلي من Zoom بمجرد أن تصبح النسخ جاهزة.
يوجد أيضًا نهج ثالث، **تكامل أحداث التدفق**، الذي يعمل مع أنواع معينة من البيانات.
#### الاستعلام الدوري عن واجهات برمجة التطبيقات الخاصة بـ Zoom مركز الاتصال
لتنزيل بيانات التفاعل، يجب الاستعلام عن نقاط نهاية واجهة برمجة التطبيقات المناسبة لـ ZCC. ومن المهم ملاحظة أن أنواع البيانات المختلفة تأتي من واجهات برمجة تطبيقات مختلفة، لذا من المحتمل أن تحتاج إلى إنشاء منطق استعلام دوري لكل نقطة نهاية ذات صلة.
تدعم العديد من واجهات برمجة التطبيقات المتعلقة بالتفاعل ضمن Reports V2 (CX تحليلات) الآن التصفية حسب وقت الانتهاء باستخدام `end_time_from` و `end_time_to`۔ فضّل هذه المعلمات عند توفرها حتى تسترجع مهام الاستعلام الدوري التفاعلات استنادًا إلى وقت انتهائها الفعلي. يساعد ذلك على تقليل السجلات المفقودة لأن بيانات التفاعل الكاملة (بما في ذلك بيانات Report V2) تُستكمل عند انتهاء التفاعل.
| للحصول على هذه البيانات... | استعلم عن واجهة برمجة التطبيقات هذه... | باستخدام هذا الحقل... | ملاحظات: |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ------------------------------------------------------ |
|
| `رابط_النسخ` | يتطلب تمكين النسخ لصندوق الوارد. |
{% hint style="danger" %}
**تحذير**
عناوين URL للتنزيل (`رابط_التنزيل`, `رابط_النسخ`, `playback_url`، وما إلى ذلك) التي توفرها واجهات برمجة التطبيقات الخاصة بـ Zoom هي **لا** روابط عامة. وهي مصممة للوصول البرمجي وتتطلب المصادقة باستخدام واجهة برمجة التطبيقات (على سبيل المثال، الرمز المميز للوصول في ترويسة Authorization) لتنزيل الملف المرتبط.
هذا يعني:
* لا يمكنك حفظ عناوين URL هذه مباشرةً في نظام CRM ليتمكن مستخدم من النقر عليها. المستخدم الذي ينقر على الرابط في متصفحه لن تتم المصادقة عليه، وسيفشل التنزيل.
* الطريقة الصحيحة هي أن تستخدم خدمتك الخلفية عنوان URL لجلب الملف. ويمكن لخدمتك بعد ذلك تخزين الملف في نظامك الخاص (مثل Amazon S3 أو Azure Blob Storage أو تخزين الملفات في نظام CRM الخاص بك) وتوفير رابط آمن لمستخدميك من هناك.
{% endhint %}
{% hint style="warning" %}
**تنبيه**
**تأخيرات المعالجة - تسجيلات الصوت والفيديو:**
هذه البيانات ليست متاحة فور انتهاء مكالمة. يجب معالجة الصوت وتحميله أولًا، وقد يستغرق ذلك عدة دقائق في المكالمات الطويلة. ولضمان ألا تفوّت التسجيلات، اضبط `query_date_type` المعامل إلى `recording_end_time` عند الاستعلام الدوري عن واجهة برمجة التطبيقات الخاصة بقائمة التسجيلات. يجلب هذا البيانات بناءً على وقت انتهاء المعالجة، وليس وقت انتهاء المكالمة.
لمهام التسوية المتمحورة حول التفاعل في Reports V2 (CX تحليلات)، استخدم نوافذ زمنية متداخلة مع `end_time_from` و `end_time_to` لتوفير هامش أمان للمعالجة المتأخرة ومشكلات التسليم العابرة.
{% endhint %}
لمزيد من المعلومات حول واجهات برمجة التطبيقات الخاصة بـ Zoom مركز الاتصال، راجع [واجهات برمجة التطبيقات لمركز الاتصال](https://developers.zoom.us/docs/api/contact-center/) التوثيق.
#### استخدم خطاف الويب للفعاليات في الوقت الحقيقي
لنهجٍ أكثر فوريةً ومبنيّ على الفعالية، يمكنك الاشتراك في خطافات الويب الخاصة بـ ZCC. وهذه هي الطريقة الأكثر كفاءةً للتكامل شبه الآني.
**كيف يعمل**
1. اشترك في الفعاليات المناسبة في سوق التطبيق الخاص بتطبيق Zoom.
2. عندما تقع فعالية، يرسل Zoom إشعارًا إلى عنوان URL الخاص بخطاف الويب (أو إلى اتصال Websocket الخاص بك).
3. تحتوي حمولة الفعالية على البيانات التي تحتاجها، إما مباشرةً أو كعنوان URL/معرّف لمكالمة متابعة لواجهة برمجة التطبيقات.
**الفعاليات الشائعة لبيانات التفاعل عبر خطاف الويب**
* **بيانات انتهاء التفاعل جاهزة:** جهة الاتصال\_center.cx\_engagement\_end\_data\_ready (تشير إلى أن بيانات تقرير انتهاء التفاعل V2 جاهزة للاسترجاع)
* **تسجيل الصوت/الفيديو:** جهة الاتصال\_center.recording\_completed (يوفّر أ `رابط_التنزيل`)
* **نسخ الصوت/الفيديو:** جهة الاتصال\_center.recording\_النسخ\_completed (يوفر `رابط_النسخ`)
* **نسخ إرسال الرسائل:** جهة الاتصال\_center.engagement\_إرسال الرسائل\_النسخ\_completed (يوفر `رابط_النسخ`)
* **ملاحظات:** جهة الاتصال\_center.engagement\_note\_added (يوفر `ملاحظة` حقلًا يحتوي على بيانات الملاحظة)
* **التصرف:** جهة الاتصال\_center.engagement\_التصرف\_added (يوفر `اسم التصرف` حقل يحتوي على بيانات التصرف)
**النمط الموصى به: تشغيل الاسترجاع عند جاهزية بيانات التفاعل**
عندما تتلقى `جهة الاتصال_center.cx_engagement_end_data_ready`، اعتبره إشارةً على أن بيانات تقرير نهاية التفاعل V2 مكتملة لذلك التفاعل. عند هذه النقطة، قم بمكالمة واجهة برمجة التطبيقات لسجل بيانات التفاعل التاريخي وأي واجهة برمجة التطبيقات أخرى ذات صلة لجمع مجموعة البيانات النهائية. في هذه الفعالية، استخدم `engagement_id` كمفتاح بحثك ثم اجلب العناصر الكاملة للتفاعل من نقاط النهاية المطلوبة لديك.
{% hint style="warning" %}
**تنبيه**
* **كن على دراية بوجود عدة فعالية:** الـ `note_added` و `التصرف_added` قد يتم تشغيل الفعاليات عدة مرات لمشاركة واحدة (على سبيل المثال، إذا حفظ أحد الوكلاء عدة ملاحظات أو تم تحويل مكالمة). يجب أن يكون منطق تطبيقك قادرًا على التعامل مع ذلك.
* **أنشئ التكرار الاحتياطي:** لا يكون تسليم الفعالية مضمونًا دائمًا بنسبة 100% (على سبيل المثال، قد تكون نقطة نهاية الخاصة بك أو اتصال websocket متوقفًا مؤقتًا).
* **استراتيجية النسخ الاحتياطي:** نوصي بتشغيل برنامج نصي للمطابقة باستخدام واجهات برمجة تطبيقات الاستقصاء مع `end_time_from` و `end_time_to` نوافذ لرصد الفعاليات الفائتة وسد فجوات البيانات.
{% endhint %}
لمزيد من المعلومات حول فعاليات خطاف الويب/Websocket الخاصة بـ Zoom مركز الاتصال، راجع [خطافات الويب لمركز الاتصال](https://developers.zoom.us/docs/api/contact-center/events/) التوثيق.
#### التكامل لفعاليات التدفق
بالنسبة إلى أنواع بيانات معينة، يمكنك دفع البيانات مباشرةً إلى نظام خارجي من محرر تدفق ZCC باستخدام نص برمجي للفعالية بلغة JavaScript.
**البيانات المدعومة والقيود:**
* **التصرف:** يمكن الوصول إليه على جميع أنواع قنوات التفاعل الواردة باستخدام `global_system.Engagement.التصرف` المتغير.
* **النسخ:** يمكن الوصول إليه فقط في تفاعلات إرسال الرسائل الواردة (على سبيل المثال، Web دردشة) باستخدام `global_system.Engagement.النسخ` المتغير.
* **مسارات متعددة:** عند العمل مع مسارات متعددة في إعدادك، خاصةً عندما يستخدم أحد المسارات `RouteTo` عند استخدام عنصر واجهة للاتصال بـ Flow آخر، من الضروري التأكد من أن برامج نصية للفعالية والمشغلات المتطابقة قد كوَّنت بشكل صحيح عبر جميع Flows.
هذه الطريقة هي الأقوى في تدفق إرسال الرسائل، حيث يمكنك دمج كلٍّ من النسخ والتصرف في فعالية واحدة.
**خطوات التكوين**
اتبع هذه الخطوات لتكوَّن التدفق الخاص بك:
{% stepper %}
{% step %}
**إضافة برنامج نصي للفعالية**
في تدفق ZCC الخاص بك (على سبيل المثال، تدفق دردشة ويب)، انقر على أداة Start.
اعثر على برامج نصية للفعالية وأضف برنامجًا نصيًا للفعالية من أجل الفعاليات، مثل إغلاق التفاعل و/أو حفظ التصرف.
{% endstep %}
{% step %}
**إضافة JavaScript المخصص الخاص بك**
يسترجع المثال أدناه كلًّا من التصرف والنسخ، ثم يرسلهما معًا إلى واجهة برمجة التطبيقات الخارجية.
```javascript
async function main () {
حاول {
// الحصول على كائن التصرف من متغيره
const التصرف_data = var_get()['global_system.Engagement.التصرف'];
// الحصول على كائن النسخ الكامل
const النسخ_data = await req.get(var_get()['global_system.Engagement.النسخ']);
// إعداد حمولة بكل البيانات التي تريد إرسالها
const payload_to_send = {
التصرف: التصرف_data.data.result,
النسخ: النسخ_data.data.result.النسخ
};
// تحديد وجهة بياناتك
const external_api_url = '';
// أرسل البيانات المجمعة إلى نظامك الخارجي
const response = await req.post(external_api_url, payload_to_send);
// سجّل الاستجابة من النظام الخارجي لأغراض استكشاف الأخطاء وإصلاحها
log.debug("استجابة واجهة برمجة التطبيقات الخارجية: " + JSON.stringify(response.data));
} catch (error) {
log.debug("حدث خطأ في سكربت فعالية النسخ: " + error);
}
}
```
{% endstep %}
{% endstepper %}
***
### الملخص والتوصيات
اختر طريقة التكامل التي تتوافق بشكل أفضل مع سير عمل وكيلك والموارد التقنية المتاحة لديك.
| إذا كان وكلاؤك يستخدمون... | إذًا فإن أفضل خيار لديك هو... | اعتبارات رئيسية: |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| موصل ZCC CTI في نظام CRM مدعوم | التكامل المدمج |
أسهل مسار
لا يتطلب أي برمجة
المزامنة لبيانات التفاعل مدمجة
|
| تطبيق Zoom Workplace أو Smart Embed | واجهة برمجة التطبيقات Webhooks بالإضافة إلى تسوية الاستطلاع المفلترة حسب وقت النهاية |
استخدم جهة الاتصال\_center.cx\_engagement\_end\_data\_ready كمشغل الاسترجاع الخاص بك
ثم طابِق مع end\_time\_from/end\_time\_to نوافذ
يُحسّن الكفاءة مع تقليل التفاعلات الفائتة
|
| تدفق إرسال الرسائل الواردة (والحاجة إلى دفع البيانات) | برامج نصية لفعالية التدفق |
متخصصة، لكنها قوية
يتطلب JavaScript
يعمل بأفضل شكل لإرسال نصوص إرسال الرسائل والتصنيفات النهائية
|
من خلال فهم هذه المسارات المختلفة، يمكنك بناء تكامل متين وموثوق يمنحك رؤية كاملة لتفاعلات عملائك. يساعدك الجمع بين الاسترجاع المشغّل بالفعالية والمطابقة المفلترة حسب وقت الانتهاء على تقليل استدعاءات واجهة برمجة التطبيقات غير الضرورية مع تحسين الاكتمال.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://library.zoom.com/technical-library/technical-library-ar/khdmat-alaamal/zoom-contact-center/expert-insights/integrate-engagement-data.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
