إنشاء واجهات Google Chat

تقدّم هذه الصفحة نظرة عامة حول كيفية إنشاء واجهات مستخدم (UI) لإضافات Google Workspace التي توفّر ميزات إضافية في Google Chat.

في Google Chat، تظهر الإضافات للمستخدمين على أنّها تطبيقات Google Chat. لمزيد من المعلومات، راجِع نظرة عامة على توسيع نطاق Google Chat.

لإنشاء واجهات لتطبيقات Chat، يمكنك استخدام المكونات الإضافية التالية:

  • عوامل التشغيل: الطرق التي يمكن لمستخدمي Google Chat من خلالها تشغيل أحد تطبيقات Chat، مثل إضافته إلى مساحة أو إرسال رسالة إليه
  • عناصر الأحداث: البيانات التي تتلقّاها تطبيقات Chat من عوامل التفعيل أو تفاعلات واجهة المستخدم
  • الإجراءات: الطرق التي يمكن لتطبيقات Chat من خلالها الردّ على التفاعلات، مثل إرسال الرسائل أو عرض واجهة مستخدم مستندة إلى بطاقات
يتلقّى تطبيق Chat عنصر حدث من عامل تشغيل "تمت الإضافة إلى مساحة".
الشكل 1: عندما يضيف مستخدم تطبيق Chat إلى مساحة، يتم تشغيل عامل التفعيل تمّت الإضافة إلى المساحة وإرسال عنصر حدث. للردّ برسالة، يعالج تطبيق Chat عنصر حدث ويعرض إجراءً ينشئ الرسالة.

يمكن لتطبيقات Chat إنشاء البطاقات وعرضها في الواجهتَين التاليتَين:

  • الرسائل التي يمكن أن تحتوي على نص، وبطاقات ثابتة أو تفاعلية، وأزرار
  • المربّعات الحوارية، وهي بطاقات تفتح في نافذة جديدة وتطلب عادةً من المستخدمين إرسال معلومات.
  • معاينات الروابط، وهي بطاقات تعرض معاينة للمعلومات حول خدمة خارجية

العوامل التي تؤدي إلى الظهور

يوضّح هذا القسم عوامل التفعيل التي تستخدمها إضافات Google Workspace في Chat.

العوامل المشغِّلة هي الطرق المحدّدة التي يستخدمها المستخدمون لتشغيل تطبيق Chat باستخدام واجهة مستخدم Chat، مثل استخدام الإشارات @أو أوامر التطبيق.

يعرض الجدول التالي عوامل تشغيل Chat ووصفًا وكيفية استجابة تطبيقات Chat عادةً:

المشغِّل الوصف الردّ المعتاد
تمّت الإضافة إلى المساحة

يضيف مستخدم تطبيق Chat إلى مساحة، أو يُثبِّت مشرف Google Workspace تطبيق Chat في مساحات الرسائل المباشرة للمستخدمين في مؤسسته. للتعرّف على تطبيقات Chat التي ثبّتها المشرفون، يُرجى الاطّلاع على مقالة تثبيت تطبيقات Marketplace في نطاقك في مستندات مركز مساعدة مشرفي Google Workspace.

 يرسل تطبيق Chat رسالة ترحيب توضّح وظائفه وكيفية تفاعل المستخدمين في المساحة معه.
رسالة

يتفاعل أحد المستخدمين مع تطبيق Chat في رسالة بإحدى الطريقتَين التاليتَين:

  • إرسال رسالة في مساحة رسالة مباشرة باستخدام تطبيق Chat
  • @الإشارة إلى تطبيق Chat في أي نوع من المساحات
  • إرسال رسالة تتضمّن رابطًا يتطابق مع نمط عنوان URL من أجل معاينات الروابط
  • يكتب نصًا في قائمة الاختيار المتعدّد لتطبيق selectionInput مصغّر.
 يردّ تطبيق Chat استنادًا إلى محتوى الرسالة. على سبيل المثال، يردّ تطبيق Chat على الأمر /about برسالة توضّح المهام التي يمكنه تنفيذها.
تمت الإزالة من المساحة

يزيل مستخدم تطبيق Chat من مساحة، أو يزيل مشرف Google Workspace تطبيق Chat لمستخدم في مؤسسته.

لا يمكن للمستخدمين إزالة تطبيقات Chat التي ثبَّتها المشرف. إذا ثبَّت مستخدم تطبيق Chat في السابق، سيظل تطبيق Chat مثبَّتًا بغض النظر عمّا إذا حاول مشرف Google Workspace إلغاء تثبيته.

 يزيل تطبيق Chat أي إشعارات واردة تم ضبطها للمساحة (مثل حذف رابط ويب للطلبات) ويُخلي أي مساحة تخزين داخلية. لا يمكن لتطبيقات Chat الردّ على هذا المشغِّل برسائل لأنّها لم تعُد عضوًا في المساحة.
أمر التطبيق

يستخدم مستخدم طلبًا سريعًا أو طلبًا يبدأ بشرطة مائلة من تطبيق Chat.

 يستجيب تطبيق Chat للأمر. على سبيل المثال، الردّ برسالة أو فتح مربّع حوار

على عكس إضافات Google Workspace الأخرى، عليك ضبط أي وظائف استدعاء ل هذه المشغّلات باستخدام Google Chat API. للحصول على إرشادات، يُرجى الاطّلاع على مقالة ضبط تطبيق Google Chat.

للردّ على عامل تشغيل، اطّلِع على الأدلة التالية:

عناصر الحدث

يحدِّد هذا القسم جميع عناصر عناصر أحداث Chat ويوضّحها. لمزيد من المعلومات، اطّلِع على مقالة عناصر الأحداث.

عنصر الحدث
commonEventObject object (CommonEventObject)
عنصر يحتوي على معلومات شائعة لجميع عناصر الأحداث، بغض النظر عن التطبيق المضيف
chat object (Chat)
عنصر يحتوي على جميع المعلومات عن تفاعلات Chat

دردشة

دردشة
chat.user object (User)
مستخدم Chat الذي تفاعل مع تطبيق Chat
chat.space object (Space)
مساحة Chat التي تفاعل فيها مستخدم مع تطبيق Chat
chat.eventTime

string (Timestamp format)

الوقت الذي حدث فيه التفاعل

حقل الربط payload

يمكن أن يكون payload واحدًا فقط مما يلي:
chat.messagePayload

object (MessagePayload)

الحمولة التي تتلقّاها تطبيقات Chat من عامل تشغيل الرسالة
chat.addedToSpacePayload

object (AddedToSpacePayload)

الحمولة التي تتلقّاها تطبيقات Chat من عامل التفعيل تمّت الإضافة إلى مساحة
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

الحمولة التي تتلقّاها تطبيقات Chat من عامل تشغيل تمت الإزالة من المساحة
chat.buttonClickedPayload

object (ButtonClickedPayload)

الحمولة التي تتلقّاها تطبيقات Chat عندما ينقر المستخدمون على زر من رسالة أو بطاقة إذا نقر مستخدم على زر لإرسال المعلومات، يحتوي العنصر commonEventObject.formInputs على القيم التي تم جمعها من المستخدم. لمعرفة التفاصيل، يُرجى الاطّلاع على جمع المعلومات من مستخدمي Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

الحمولة التي تتلقّاها تطبيقات Chat عندما يكتب المستخدمون نصًا في قائمة الاختيار المتعدّد لتطبيق مصغّر selectionInput يمكن لتطبيقات المحادثات استخدام عنصر الحدث هذا لتعبئة العناصر المقترَحة من مصدر بيانات ديناميكي. على سبيل المثال، لتعبئة طلبات الدعم من مصدر بيانات خارجي، يمكن لتطبيق Chat طلب البحث من مصدر البيانات استنادًا إلى ما يطلبه المستخدم في القائمة، ثم عرض أي طلبات دعم مطابقة كعناصر قابلة للاختيار.

يحتوي العنصر CommonEventObject.parameters['autocomplete_widget_query'] على قيمة السلسلة التي يكتبها المستخدم في القائمة.

chat.appCommandPayload

object (AppCommandPayload)

الحمولة التي تتلقّاها تطبيقات Chat عندما يستخدم مستخدم أمرًا من تطبيق Chat

الحمولة

استنادًا إلى نوع التفاعل، يحتوي الحدث على حمولة تحتوي على مورد واحد أو أكثر من Chat API.

الحمولة في الرسالة
MessagePayload
chat.messagePayload.message object (Message)
رسالة Chat التي أدّت إلى الحدث.
chat.messagePayload.space object (Space)
مساحة Chat التي أرسل فيها أحد المستخدمين الرسالة التي أدّت إلى تشغيل تطبيق Chat.

تمت إضافتها إلى الحمولة في المساحة
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
مساحة Chat التي أضاف إليها المستخدم تطبيق Chat أو ثبَّته فيها.

عندما يُثبِّت المشرفون تطبيقات Chat، يتم ضبط الحقل space.adminInstalled على true.

chat.addedToSpacePayload.interactionAdd boolean
ما إذا كان المستخدم يضيف تطبيق Chat إلى مساحة باستخدام رسالة على سبيل المثال، الإشارة إلى تطبيق Chat باستخدام @ أو استخدام أمر يبدأ بشرطة مائلة إذا كان true، تُرسِل Chat عنصر حدث آخر يحتوي على messagePayload يحتوي على معلومات عن الرسالة.

تمت إزالته من الحمولة في المساحة
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
مساحة Chat التي أزال المستخدم منها تطبيق Chat أو ألغى تثبيته

عندما يُلغي المشرفون تثبيت تطبيقات Chat، يتم ضبط الحقل space.adminInstalled على false.

الحمولة عند النقر على الزر
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
رسالة Chat التي تحتوي على الزر الذي نقر عليه المستخدم
chat.buttonClickedPayload.space object (Space)
مساحة Chat التي نقر فيها المستخدم على زر من رسالة في تطبيق Chat
chat.buttonClickedPayload.isDialogEvent boolean
يشير ذلك إلى ما إذا نقر المستخدم على الزر للتفاعل مع مربّع حوار.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
إذا كان isDialogEvent هو true، نوع التفاعل في مربّع حوار.

التعداد DialogEventType

يمكن أن تكون قيمة dialogEventType إحدى القيم التالية فقط:
TYPE_UNSPECIFIED القيمة التلقائية غير محدد
REQUEST_DIALOG يطلب أحد المستخدمين فتح مربّع حوار. على سبيل المثال، يستخدمون الأمر slash أو ينقرون على زر من رسالة.
SUBMIT_DIALOG ينقر مستخدم على عنصر تفاعلي ضمن مربّع حوار. على سبيل المثال، يملؤه المستخدم معلومات في مربّع حوار وينقر على زر لإرساله.

الحمولة المعدَّلة للأداة المصغّرة
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
مساحة Chat التي حدث فيها التفاعل

الحمولة في أمر التطبيق
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
البيانات الوصفية عن الأمر الذي استخدمه المستخدم وكيفية تفعيله
chat.appCommandPayload.space object (Space)
مساحة Chat التي استخدم فيها المستخدم الأمر.
chat.appCommandPayload.thread object (Thread)
إذا حدث التفاعل في سلسلة محادثات، سلسلة محادثات Chat التي استخدم فيها المستخدم الأمر.
chat.appCommandPayload.message object (Message)
الرسالة التي أرسلها المستخدم باستخدام الأمر slash
chat.appCommandPayload.configCompleteRedirectUri string
إذا كان التفويض أو الإعداد مطلوبًا للطلب، يجب إدخال عنوان URL لإعادة توجيه المستخدم إليه بعد إكمال العملية خارج Google Chat.
chat.appCommandPayload.isDialogEvent boolean
ما إذا كان الأمر سيفتح مربّع حوار.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
نوع التفاعل مع مربّع حوار

التعداد DialogEventType

يمكن أن تكون قيمة dialogEventType إحدى القيم التالية فقط:
TYPE_UNSPECIFIED القيمة التلقائية غير محدد
REQUEST_DIALOG يطلب أحد المستخدمين فتح مربّع حوار. على سبيل المثال، يستخدمون الأمر slash أو ينقرون على زر من رسالة.
SUBMIT_DIALOG ينقر مستخدم على عنصر تفاعلي ضمن مربّع حوار. على سبيل المثال، يملؤه المستخدم معلومات في مربّع حوار وينقر على زر لإرساله.
البيانات الوصفية لأمر التطبيق
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

رقم تعريف الأمر.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
نوع الطلب.

التعداد AppCommandType

يمكن أن تكون قيمة AppCommandType إحدى القيم التالية فقط:
APP_COMMAND_TYPE_UNSPECIFIED القيمة التلقائية غير محدد
SLASH_COMMAND يستخدم المستخدم الأمر من خلال إرسال رسالة تبدأ بشرطة مائلة /.

إجراءات تتعلّق بالمحادثة

يوضّح هذا القسم كيفية استخدام تطبيقات Chat الإجراءات الإضافية للردّ على تفاعلات المستخدمين.

للردّ بإجراء إضافي، يجب أن يستجيب تطبيق Chat في غضون 30 ثانية، ويجب أن يتم نشر الردّ في المساحة التي حدث فيها التفاعل. بخلاف ذلك، يجب أن يُعدّ تطبيق Chat مصادقة ويطلب بيانات من Google Chat API للردّ.

يمكن لتطبيقات المحادثة التعامل مع التفاعلات والردّ عليها بعدة طرق. في كثير من الحالات، ترد تطبيقات Chat برسالة. يمكن لتطبيقات المحادثة أيضًا البحث عن بعض المعلومات من مصدر بيانات، أو تسجيل معلومات عنصر الحدث، أو أي شيء آخر. يُعدّ سلوك المعالجة هذا هو ما يحدِّد بشكل أساسي تطبيق Google Chat.

للردّ على تفاعلات المستخدمين، يجب أن تعالج تطبيقات Chat كائن الحدث المقابل وأن تعرض أحد كائنات JSON التالية:

الردّ المطلوب من تطبيق Chat الإجراء المطلوب للإرجاع
إرسال رسالة أو تعديلها DataActions
فتح مربّع حوار أو تعديله أو إغلاقه RenderActions
لـ جمع المعلومات من بطاقة أو مربّع حوار، يمكنك اقتراح عناصر اختيار استنادًا إلى ما يطلبه المستخدمون في قائمة اختيار متعدّد. RenderActions
معاينة الروابط في الرسائل التي يرسلها مستخدمو Chat في مساحة DataActions

الردّ باستخدام Google Chat API

بدلاً من عرض إجراء إضافي، قد تحتاج تطبيقات Chat إلى استخدام Google Chat API للردّ على أحد التفاعلات. على سبيل المثال، يجب أن تستدعي تطبيقات Chat واجهة برمجة التطبيقات Google Chat API للقيام بأي مما يلي:

  • الردّ على تفاعل بعد 30 ثانية
  • تنفيذ المهام خارج المساحة التي حدث فيها التفاعل
  • تنفيذ مهام في Chat غير متاحة كأحد الإجراءات الإضافية على سبيل المثال، يمكنك إدراج المساحات التي يكون فيها مستخدم أو تطبيق Chat عضوًا، أو إضافة مستخدمين إلى المساحة.
  • تنفيذ المهام نيابةً عن مستخدم Chat (يتطلب ذلك مصادقة المستخدم)

للتعرّف على كيفية المصادقة على Chat API والاتّصال بها، يُرجى الاطّلاع على نظرة عامة على Chat API.