إرسال رسائل Google Chat

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

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

  • نموذج التواصل من خلال أمر يبدأ بشرطة مائلة
    الشكل 1. يردّ تطبيق Chat على أحد الأوامر التي تبدأ بشرطة مائلة من خلال رسالة نصية وزر.
  • نموذج تواصل في مربّع حوار
    الشكل 2. يفتح تطبيق Chat مربّع حوار يمكن للمستخدمين فيه إدخال المعلومات.
  • رسالة بطاقة تتضمّن تطبيقات مصغّرة لإدخال البيانات في النموذج
    الشكل 5. يُرسِل تطبيق Chat رسالة تتضمّن نصًا وبطاقة تفاعلية.

المتطلبات الأساسية

Node.js

إضافة Google Workspace التي توفّر ميزات إضافية في Google Chat لإنشاء تطبيق، أكمِل البدء السريع لاستخدام بروتوكول HTTP.

برمجة تطبيقات

إضافة Google Workspace التي توفّر ميزات إضافية في Google Chat لإنشاء تطبيق، أكمِل الخطوات الأساسية لبدء استخدام Apps Script.

تصميم الرسالة

يمكن أن تتضمّن تطبيقات المحادثات أيًا مما يلي في الرسالة:

  • النص الذي يحتوي على روابط تشعّبية وإشارات إلى مستخدمين عبر @ ورموز تعبيرية
  • بطاقة واحدة أو أكثر، يمكن أن تظهر في رسالة أو تفتح في نافذة جديدة كمربّع حوار
  • تطبيق مصغّر واحد أو أكثر من التطبيقات الملحقة، وهي أزرار تظهر بعد أي نص أو بطاقات في رسالة

للتعرّف على كيفية تصميم الرسائل، يُرجى الاطّلاع على موارد برمجة التطبيقات التالية لـ Google Chat API:

الرد برسالة

يمكن لتطبيقات المحادثة الردّ برسالة على أيّ من يلي: العوامل المشغِّلة أو التفاعلات:

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

بخلاف ذلك، يمكن لتطبيقات Chat إرسال الرسائل بشكل استباقي من خلال الاتصال بواجهة برمجة تطبيقات Google Chat.

للردّ من خلال رسالة، أعِد الإجراء DataActions مع عنصر CreateMessageAction:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

استبدِل MESSAGE بمورد Message من Chat API. لمزيد من المعلومات حول آلية عمل الإجراءات، يُرجى الاطّلاع على مقالة إجراءات Chat.

في المثال التالي، ينشئ تطبيق Chat رسالة نصية ويرسلها عند إضافته إلى مساحة. لإرسال رسالة نصية عندما يُضيف أحد المستخدمين تطبيق Chat إلى مساحة، يستجيب تطبيق Chat للعامل المشغِّل تمّت الإضافة إلى مساحة من خلال عرض الإجراء DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace Add-on.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 *                     introduces the app and helps people get started with it.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar' +
            'from Google Chat. Take a look at your schedule today by typing' +
            '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn' +
            'what else I can do, type `/help`.'
    }}}}});
  }
};

برمجة تطبيقات

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 *                  introduces the app and helps people get started with it.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar' +
          'from Google Chat. Take a look at your schedule today by typing' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn' +
          'what else I can do, type `/help`.'
  }}}}};
}

تعرِض نموذج التعليمات البرمجية الرسالة النصية التالية:

مثال على رسالة الإعداد

للحصول على أمثلة إضافية حول كيفية الردّ من خلال رسالة، اطّلِع على المراجع التالية:

تعديل رسالة

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

لتعديل رسالة في تطبيق Chat، استبدِل الإجراء DataActions برمز UpdateMessageAction، كما هو موضّح في المثال التالي:

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

استبدِل MESSAGE بمورد Message من Chat API.

لمزيد من المعلومات حول آلية عمل الإجراءات، يُرجى الاطّلاع على مقالة إجراءات Chat.

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

الردّ على التفاعلات أو إرسال رسائل استباقية باستخدام Google Chat API

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

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

لإرسال رسالة باستخدام Chat API، عليك إعداد المصادقة واستخدام طريقة create() في مورد Message. لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إرسال رسالة باستخدام Google Chat API.