الردّ على أوامر تطبيق Google Chat

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

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

لتحديد ما إذا كان عليك إنشاء أوامر وفهم كيفية تصميم تفاعلات المستخدمين، يُرجى الاطّلاع على تحديد جميع رحلات المستخدمين.

أنواع أوامر تطبيق Chat

1. الأوامر التي تبدأ بشرطة مائلة: يمكن للمستخدمين اختيار أمر يبدأ بشرطة مائلة من القائمة أو كتابة شرطة مائلة (/) ثم نص محدّد مسبقًا، مثل /about. تتطلّب تطبيقات Chat عادةً نص وسيطة للأمر الذي يبدأ بشرطة مائلة.

   أنشئ أمرًا يبدأ بشرطة مائلة إذا كان تطبيق Chat يتطلّب إدخال معلومات إضافية من المستخدم. على سبيل المثال، يمكنك إنشاء أمر يبدأ بشرطة مائلة باسم /search يتم تشغيله بعد أن يُدخِل المستخدم عبارة للبحث عنها، مثل /search receipts.

2. الأوامر السريعة: يستخدم المستخدمون الأوامر من خلال فتح القائمة من منطقة الردّ على رسالة محادثة. لاستخدام أمر، ينقرون على إضافة ويختارون أمرًا من القائمة.

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

3. إجراءات الرسائل: يستخدم المستخدمون إجراءات الرسائل من خلال تمرير مؤشر الماوس فوق رسالة و النقر على قائمة النقاط الثلاث. لاستخدام أمر، يفتحون قائمة النقاط الثلاث ويختارون أمرًا من القائمة.

   أنشئ إجراء مقترحًا إذا كان بإمكان تطبيق Chat تنفيذ إجراءات استنادًا إلى سياق رسالة.

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

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

إعداد الأمر

يوضّح هذا القسم كيفية إكمال الخطوات التالية لإعداد أمر:

1. إنشاء اسم ووصف للأمر
2. ضبط الأمر في Google Cloud Console

تسمية الأمر ووصفه

اسم الأمر هو ما يكتبه المستخدمون أو يختارونه لاستدعاء تطبيق Chat. ويظهر أيضًا وصف قصير أسفل الاسم، لتشجيع المستخدمين على معرفة كيفية استخدام الأمر:

عند اختيار اسم ووصف لأمرك، ضَع في اعتبارك الاقتراحات التالية:

لتسمية أمر:

• استخدِم كلمات أو عبارات قصيرة وواضحة وقابلة للتنفيذ لجعل الأوامر واضحة للمستخدم. على سبيل المثال، بدلاً من الاسم Create a reminder، استخدِم Remind me.
• ضَع في اعتبارك استخدام اسم فريد أو شائع لأمرك. إذا كان أمرك يصف تفاعلاً أو ميزة نموذجية، يمكنك استخدام اسم شائع يعرفه المستخدمون ويتوقعونه، مثل Settings أو Feedback. بخلاف ذلك، حاوِل استخدام أسماء أوامر فريدة، لأنّه إذا كان اسم أمرك هو نفسه في تطبيقات Chat الأخرى، على المستخدم فلترة الأوامر المشابهة للعثور على أمرك واستخدامه.

لوصف أمر:

• اجعل الوصف قصيرًا وواضحًا ليعرف المستخدمون ما يمكن توقّعه عند استخدام الأمر.
• أخبِر المستخدمين إذا كانت هناك أي متطلبات تنسيق للأمر. على سبيل المثال، إذا أنشأت أمرًا يبدأ بشرطة مائلة ويتطلّب نص وسيطة، اضبط الوصف على شيء مثل Remind me to do [something] at [time]
• أخبِر المستخدمين إذا كان تطبيق Chat يردّ على الجميع في المساحة، أو بشكل خاص على المستخدم الذي يستدعي الأمر. على سبيل المثال، بالنسبة إلى الأمر السريع About، يمكنك وصفه على أنّه Learn about this app (Only visible to you).

ضبط الأمر في Google Cloud Console

لإنشاء أمر يبدأ بشرطة مائلة أو أمر سريع أو إجراء رسالة، عليك تحديد معلومات عن الأمر أو الإجراء في إعدادات تطبيق Chat لواجهة Google Chat API.

لضبط أمر في Google Chat API، أكمل الخطوات التالية:

1. في Google Cloud Console، انقر على "القائمة" menu > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API

   الانتقال إلى صفحة Google Chat API

2. انقر على الإعداد.

3. ضمن إعدادات الاتصال، انتقِل إلى المشغّلات وحدِّد تفاصيل نقطة النهاية. عليك استخدام هذا المشغّل في القسم التالي للردّ على الأمر.

   1. عنوان URL لنقطة نهاية HTTP: يمكنك تحديد عنوان URL واحد لنقطة نهاية HTTP الشائعة هنا. بدلاً من ذلك، لاستخدام نقاط نهاية HTTP مختلفة لمشغّلات مختلفة، حدِّد نقطة النهاية مباشرةً في حقل أمر التطبيق.
   2. برمجة التطبيقات: أدخِل رقم تعريف عملية نشر "برمجة التطبيقات". سيتم استدعاء الدالة onAppCommand تلقائيًا. لاستخدام دالة مختلفة في "برمجة التطبيقات"، حدِّد اسم الدالة المخصّصة في حقل أمر التطبيق.

4. ضمن الأوامر ، انقر على إضافة أمر.

5. أدخِل المعلومات التالية عن الأمر:

   1. رقم تعريف الأمر: رقم من 1 إلى 1000 يستخدمه تطبيق Chat للتعرّف على الأمر وعرض ردّ.
   2. الوصف: النص الذي يوضّح كيفية استخدام الأمر وتنسيقه. يمكن أن يصل طول الأوصاف إلى 50 حرفًا.
   3. نوع الأمر: اختَر أمرًا سريعًا أو أمرًا يبدأ بشرطة مائلة أو إجراء مقترح.
   4. حدِّد اسمًا للأمر:
      • اسم الأمر السريع: الاسم المعروض الذي يختاره المستخدمون من القائمة لاستدعاء الأمر يمكن أن يصل طوله إلى 50 حرفًا ويتضمّن أحرفًا خاصة. على سبيل المثال، Remind me.
      • اسم أمر يبدأ بشرطة مائلة: النص الذي يكتبه المستخدمون لاستدعاء الأمر في رسالة. يجب أن يبدأ بشرطة مائلة، وأن يحتوي على نص فقط، ويمكن أن يصل طوله إلى 50 حرفًا. على سبيل المثال، /remindMe.
      • اسم إجراء الرسالة: الاسم المعروض الذي يختاره المستخدمون من القائمة لاستدعاء إجراء الرسالة يمكن أن يصل طوله إلى 50 حرفًا ويتضمّن أحرفًا خاصة. على سبيل المثال، Remind me.

6. اختياري: رسالة إشعار التحميل: رسالة إشعار مؤقتة يتم عرضها للمستخدم أثناء تنفيذ إجراء الرسالة لا تتوفّر هذه الرسالة إلا لإجراءات الرسائل التي لا تفتح مربعات حوار.

7. اختياري: إذا كنت تريد أن يردّ تطبيق Chat على الأمر باستخدام مربع حوار، ضَع علامة في مربّع الاختيار فتح مربع حوار.

8. انقر على حفظ.

تم الآن ضبط الأمر لتطبيق Chat.

الردّ على أمر

عندما يستخدم المستخدمون أمرًا، يتلقّى تطبيق Chat عنصر حدث. يحتوي حمولة الحدث على عنصر appCommandPayload يتضمّن تفاصيل عن الأمر الذي تم استدعاؤه (بما في ذلك رقم تعريف الأمر ونوع الأمر)، ما يتيح لك عرض ردّ مناسب. يتم إرسال عنصر الحدث إلى نقطة نهاية HTTP أو دالة "برمجة التطبيقات" التي حدّدتها عند ضبط مشغّل أمر التطبيق الحدث.

يعرض الرمز البرمجي التالي مثالاً على تطبيق Chat يردّ على الأمر الذي يبدأ بشرطة مائلة /about برسالة نصية. للردّ على الأوامر التي تبدأ بشرطة مائلة، يعالج تطبيق Chat عناصر الأحداث من مشغّل أمر التطبيق. عندما تحتوي حمولة عنصر حدث على رقم تعريف أمر يبدأ بشرطة مائلة، يعرض تطبيق Chat الإجراء DataActions مع عنصر createMessageAction

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'The Avatar app replies to Google Chat messages.'
      }}}}};
  }
}

لاستخدام عينة التعليمات البرمجية هذه، استبدِل ABOUT_COMMAND_ID ب رقم تعريف الأمر الذي حدّدته عند ضبط الأمر في Chat API.

الردّ على إجراء مقترح

يعرض الرمز البرمجي التالي مثالاً على تطبيق Chat يردّ على الإجراء المقترح ذكّرني برسالة نصية. للردّ على إجراءات الرسائل، يعالج تطبيق Chat عناصر الأحداث من مشغّل أمر التطبيق. عندما تحتوي حمولة عنصر حدث على رقم تعريف أمر إجراء مقترح، يعرض تطبيق Chat الإجراء DataActions مع عنصر createMessageAction object:

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return res.json({
      "hostAppDataAction": {
        "chatDataAction": {
          "createMessageAction": {
            "message": {
              "text": `Setting a reminder for message: "${messageText}"`
            }
          }
        }
      }
    });
  }
}

def on_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "text": f'Setting a reminder for message: "{message_text}"'
                        }
                    }
                }
            }
        }

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = payload.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

لاستخدام عينة التعليمات البرمجية هذه، استبدِل REMIND_ME_COMMAND_ID برقم تعريف الأمر الذي حدّدته عند ضبط الأمر في Chat API.

اختبار الأمر

لاختبار الأمر والرمز البرمجي، يُرجى الاطّلاع على اختبار الميزات التفاعلية لتطبيقات Google Chat.

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

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

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