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

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

  • نموذج التواصل من الأمر الذي يبدأ بشرطة مائلة
    الشكل 1. A Chat app responds to a slash command with a text message and button.
  • نموذج الاتصال في مربّع حوار
    الشكل 2. A يفتح تطبيق 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 لتنفيذ أي مما يلي:

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

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