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

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

  • نموذج التواصل من الأمر الذي يبدأ بشرطة مائلة
    الشكل 1. A Chat app responds to a slash command with a text message and button.
  • نموذج الاتصال في مربّع حوار
    الشكل 2. A يفتح تطبيق Chat مربّع حوار يمكن للمستخدمين إدخال المعلومات فيه.
  • رسالة البطاقة التي تحتوي على أدوات إدخال النموذج
    الشكل 5. أ يرسل تطبيق Chat رسالة تتضمّن نصًا وبطاقة تفاعلية.

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

HTTP

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

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

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

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

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

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

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

الرد برسالة

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

بخلاف ذلك، يمكن لتطبيقات 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.
 */
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`.'
      }}
    }}})

Java

@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، عليك عرض الإجراء 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.