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

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

  • نموذج تواصل من أمر يبدأ بشرطة مائلة

    يردّ تطبيق Chat على أمر يبدأ بشرطة مائلة برسالة نصية وزر.

  • نموذج الاتصال في مربّع حوار

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

  • رسالة البطاقة التي تحتوي على أدوات إدخال النموذج

    يرسل تطبيق Chat رسالة تحتوي على نص وبطاقة تفاعلية.

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

HTTP

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

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

إضافة Google Workspace توسّع نطاق Google Chat. لإنشاء إضافة، يُرجى إكمال دليل البدء السريع لبرمجة التطبيقات.

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

يمكن لتطبيقات Chat تضمين أي مما يلي في الرسالة:

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

للتعرّف على تصميم الرسائل، يُرجى الاطّلاع على مستندات Google Chat API التالية:

الرد برسالة

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

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

بخلاف ذلك، يمكن لتطبيقات Chat إرسال رسائل بشكل استباقي من خلال استدعاء Google Chat API.

للردّ برسالة، عليك عرض الإجراء 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.
 */
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`.'
    }}}}});
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "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`.'
      }}
    }}})

جافا

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if(!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "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.
 */
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 أيضًا تعديل الرسائل التي ترسلها. على سبيل المثال، لتعديل رسالة بعد أن يُرسِل المستخدم مربّع حوار أو ينقر على زر في رسالة

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

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

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

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

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

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

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

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

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