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

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

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

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

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

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

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

    يرسل تطبيق Chat رسالة تتضمّن نصًا وبطاقة تفاعلية.

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

HTTP

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

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

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

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

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

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

للتعرّف على كيفية تصميم الرسائل، اطّلِع على مستندات 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.
 */
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، عليك عرض الإجراء 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.