تلقّي تفاعلات المستخدمين والاستجابة لها

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

لإنشاء واجهات تفاعلية لتطبيقات Chat، يمكنك استخدام المكوّنات التالية:

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

يمكن لتطبيقات Chat إنشاء واجهات وعرضها بالطرق التالية:

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

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

• حساب Google Workspace تابع لـ Business أو Enterprise مع إمكانية الوصول إلى Google Chat
• أنشئ مشروعًا على Google Cloud.
• ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
• تفعيل واجهة برمجة تطبيقات Google Chat وضبط إعداداتها

طريقة عمل تفاعلات المستخدمين

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

يوضّح المخطّط التالي كيفية معالجة تطبيقات Google Chat لتفاعلات المستخدمين والردّ عليها:

العوامل التي تؤدي إلى الظهور

المشغّلات هي الطرق المحدّدة التي يستدعي بها المستخدمون تطبيق Chat باستخدام واجهة مستخدم Chat، مثل استخدام الإشارات @أو أوامر التطبيق.

يعرض الجدول التالي مشغّلات Chat ووصفًا لها وكيفية استجابة تطبيقات Chat عادةً:

يمكنك ضبط نقاط النهاية أو وظائف معاودة الاتصال لهذه المشغّلات في وحدة تحكّم Google Cloud على صفحة الإعدادات في Chat API. للحصول على تعليمات مفصّلة، يُرجى الاطّلاع على إعداد Google Chat API.

ضبط الطلبات الأولية

تساعد الطلبات الأولية المستخدمين في التعرّف على وظائف تطبيق Chat عند فتح رسالة مباشرة على الخاص فارغة بينك وبين تطبيقك. يمكنك ضبط ما يصل إلى ثلاثة طلبات أولية.

لإضافة طلبات جاهزة لبدء المحادثة وضبطها، اتّبِع الخطوات التالية:

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة الإعدادات الخاصة بواجهة برمجة تطبيقات Chat:

   الانتقال إلى صفحة "إعدادات واجهة برمجة تطبيقات Chat"

2. ضمن الميزات التفاعلية، ابحث عن عبارات بدء المحادثة وانقر على إضافة عبارة.

3. في حقل الترتيب (من 1 إلى 3)، أدخِل رقمًا من 1 إلى 3 لتحديد ترتيب العرض.

4. ضمن اختيار النوع، اختَر طريقة عمل الطلب:

   • طلب نصي: يملأ خانة إدخال المحتوى بنص محدّد مسبقًا عندما ينقر المستخدم على شريحة الطلب.
   • موجه الأوامر: ينفّذ أمرًا مسجّلاً من أوامر تبدأ بشرطة مائلة أو الأوامر السريعة عند النقر عليه. لا يمكن اختيار الأوامر التي تتطلّب وسيطات إضافية.

5. اضبط الطلب استنادًا إلى نوع التحديد:

   • إذا اخترت "طلب نصي":

     1. في حقل العنوان، أدخِل عنوان الطلب الذي يظهر على الشريحة (30 حرفًا كحدّ أقصى).
     2. في نص الطلب، أدخِل النص الذي يظهر في خانة إدخال المحتوى (60 حرفًا كحد أقصى).
     3. اختياري: أضِف عناوين ونصوصًا مترجَمة للمستخدمين بلغات أخرى:
     4. ضمن الطلبات المترجمة، انقر على إضافة لغة.
     5. في اللغة، اختَر لغة معتمَدة من القائمة المنسدلة.
     6. في العنوان المتوافق مع اللغة المحلية، أدخِل العنوان المتوافق مع اللغة المحلية (30 حرفًا كحدّ أقصى).
     7. في نص الطلب المترجَم، أدخِل نص الطلب المترجَم (60 حرفًا كحد أقصى).
     8. كرِّر الخطوات لإضافة المزيد من اللغات حسب الحاجة.

   • في حال اختيار "موجه الأوامر":

     1. في أمر يبدأ بشرطة مائلة / الأمر السريع، اختَر الأمر من القائمة المنسدلة.

6. انقر على تم، ثم على حفظ في أسفل الصفحة.

التعامل مع عمليات إعادة محاولة طلبات HTTP إلى خدمتك

إذا تعذّر إرسال طلب HTTPS إلى خدمتك (مثل انتهاء المهلة أو حدوث عطل مؤقت في الشبكة أو ظهور رمز حالة HTTPS غير 2xx)، قد يعيد Google Chat محاولة التسليم عدة مرات خلال بضع دقائق (ولكن هذا ليس مضمونًا). نتيجةً لذلك، قد يتلقّى تطبيق Chat الحدث نفسه عدّة مرات في بعض الحالات. إذا اكتمل الطلب بنجاح ولكن تم عرض حمولة استجابة غير صالحة، لن يعيد Google Chat محاولة إرسال الطلب.

عناصر الحدث

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

حمولة عنصر الحدث

يتضمّن كل عنصر من عناصر أحداث Chat commonEventObject مع تفاصيل المضيف والمنصة (hostApp: "CHAT" وclientPlatform وuserLocale وuserTimezone وparameters وformInputs) وعنصر chat يحتوي على سياق خاص بـ Chat:

• بالنسبة إلى مشغّل صفحة التطبيق الرئيسية (عندما يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة على الخاص مع تطبيق Chat)، يحتوي العنصر chat على chat.user وchat.eventTime بدون حقل payload موحّد. عندما ينقر المستخدم على زر في بطاقة الصفحة الرئيسية، يتضمّن عنصر الحدث chat.buttonClickedPayload بالإضافة إلى commonEventObject.parameters (وcommonEventObject.formInputs إذا كانت البطاقة تحتوي على إدخالات نموذج).
• بالنسبة إلى التفاعلات مع المساحات والرسائل (تمت الإضافة إلى المساحة أو الرسالة أو تمت الإزالة من المساحة أو أمر التطبيق أو التفاعلات مع الأزرار والأدوات)، يتضمّن العنصر chat كلاً من chat.user وchat.space وchat.eventTime وحمولة التفاعل المقابلة:
  • ‫messagePayload: يحتوي على space وmessage وconfigCompleteRedirectUri عندما يرسل المستخدم رسالة.
  • addedToSpacePayload: يحتوي على space وinteractionAdd وconfigCompleteRedirectUri عند إضافة تطبيق Chat إلى مساحة.
  • removedFromSpacePayload: يحتوي على space عند إزالة تطبيق Chat من مساحة.
  • ‫buttonClickedPayload: يحتوي على space وmessage وisDialogEvent وdialogEventType عندما ينقر المستخدم على زر في بطاقة أو مربّع حوار.
  • ‫widgetUpdatedPayload: يحتوي على space عندما يتفاعل المستخدم مع أداة، مثل الكتابة في قائمة اختيار متعدّد تتضمّن مصدر بيانات خارجيًا.
  • ‫appCommandPayload: يحتوي على space وmessage وappCommandMetadata وisDialogEvent وdialogEventType وconfigCompleteRedirectUri عندما ينفّذ المستخدم أمر تطبيق.

لمزيد من المعلومات حول عناصر أحداث الإضافات في Chat وتطبيقات Google Workspace الأخرى، يُرجى الاطّلاع على عناصر الأحداث.

تقديم ردّ

يوضّح هذا القسم كيف تستخدم تطبيقات Chat الإجراءات للردّ بشكل متزامن على تفاعلات المستخدمين.

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

للردّ على تفاعلات المستخدمين بشكل متزامن، يعالج تطبيق Chat عنصر الحدث الوارد ويعرض أحد عناصر JSON التالية:

• ‫DataActions: لإنشاء رسائل المحادثة أو تعديلها (CreateMessageAction وUpdateMessageAction) أو إرفاق معاينات الروابط (UpdateInlinePreviewAction) باستخدام chatDataActionMarkup
• RenderActions: لإنشاء صفحة رئيسية أو مربّع حوار أو تعديلهما أو إغلاقهما (pushCard وupdateCard وendNavigation: "CLOSE_DIALOG")، أو لتقديم اقتراحات إدخال ديناميكية لقائمة اختيار متعدّد (modifyCard).
• ‫AuthorizationError: يطلب من المستخدمين إدخال بطاقة تفويض أساسية (basic_authorization_prompt) لتسجيل الدخول أو إثبات ملكية حساب على خدمة خارجية.

يوضّح الجدول التالي كيف يمكن لتطبيقات Chat الردّ باستخدام الإجراءات. يمكن لتطبيقات Chat عرض عناصر JSON مباشرةً أو إنشاء الرد باستخدام AddOnResponseService وCardService في "برمجة تطبيقات Google".

الرد برسالة

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

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

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

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

للردّ برسالة، أرسِل الرمز DataActions مع كائن CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

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

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

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @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`.'
    }}}}});
  }
};

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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @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": <var>MESSAGE</var>
      }
    }
  }
}

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

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

الردّ بشكل غير متزامن باستخدام Google Chat API

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

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

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

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

لإرسال رسالة باستخدام Chat API، عليك إعداد المصادقة واستدعاء الطريقة spaces.messages.create. لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إرسال رسالة. للحصول على أدلة حول استخدام طرق إضافية في Chat API، يُرجى الاطّلاع على نظرة عامة على Chat API.

المواضيع ذات الصلة

• ضبط إعدادات Google Chat API
• إرسال رسالة
• الردّ على الأوامر
• فتح مربّعات الحوار التفاعلية
• قراءة بيانات النماذج التي أدخلها المستخدمون على البطاقات
• روابط المعاينة
• إنشاء صفحة رئيسية لتطبيق Chat
• التحقّق من الطلبات الواردة من Chat
• اختبار الميزات التفاعلية لتطبيقات Google Chat

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      '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`.'
    });
  }
};

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.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@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 Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return 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`.");
      default:
        return new Message();
    }
  }
}

/**
 * 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 onAddToSpace(event) {
  return {
    '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`.'
  };
}