تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

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

يمكنك إنشاء أوامر تطبيق Chat كأوامر تبدأ بشرطة مائلة أو أوامر سريعة أو إجراءات رسائل. لاستخدام كل نوع من الأوامر، يمكن للمستخدمين إجراء ما يلي:

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

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

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

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

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

يكتشف المستخدم قائمة بالأوامر التي تبدأ بشرطة مائلة والأوامر السريعة. — يعثر المستخدمون على قائمة بالأوامر التي تبدأ بشرطة مائلة والأوامر السريعة.

يعثر المستخدم على قائمة سياقية للرسالة تحتوي على إجراء خاص بالرسالة. — يعثر المستخدمون على قائمة سياق رسالة تحتوي على إجراء رسالة "ذكِّرني".

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

Node.js

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

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

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

Python

جافا

إعداد الأمر

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

إنشاء اسم ووصف للأمر
ضبط الأمر في 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، يُرجى إكمال الخطوات التالية:

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

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

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

الردّ على أمر

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

رسالة خاصة لتطبيق Cymbal Labs Chat. تشير الرسالة إلى أنّ تطبيق Chat تم إنشاؤه بواسطة Cymbal Labs وتتضمّن رابطًا إلى المستندات ورابطًا للتواصل مع فريق الدعم. — يردّ تطبيق Chat بشكل خاص على الأمر الذي يبدأ بشرطة مائلة `/help` لشرح كيفية الحصول على الدعم.

للردّ على كل نوع من الأوامر، عليك معالجة أنواع الأحداث المختلفة وعناصر البيانات الوصفية في حمولة الحدث:

نوع الأمر	نوع الحدث	البيانات الوصفية للأمر
أمر يبدأ بشرطة مائلة	`MESSAGE`	`message.slashCommand` أو `message.annotation.slashCommand`
أمر سريع	`APP_COMMAND`	`appCommandMetadata`
إجراء رسالة	`APP_COMMAND`	`appCommandMetadata`

للتعرّف على كيفية الردّ على أمر باستخدام رسالة، يُرجى الاطّلاع على الأقسام التالية.

الردّ على أمر يبدأ بشرطة مائلة

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

Node.js

node/avatar-app/index.js

عرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

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

apps-script/avatar-app/avatar-app.gs

عرض على GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

عرض على GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

جافا

java/avatar-app/src/main/java/AvatarApp.java

عرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

استبدِل ABOUT_COMMAND_ID برقم تعريف الأمر الذي حدّدته عند ضبط الأمر في Google Cloud Console.

الردّ على أمر سريع

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

Node.js

node/avatar-app/index.js

عرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

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

apps-script/avatar-app/avatar-app.gs

عرض على GitHub

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

عرض على GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

جافا

java/avatar-app/src/main/java/AvatarApp.java

عرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

استبدِل HELP_COMMAND_ID برقم تعريف الأمر الذي حدّدته عند ضبط الأمر في Google Cloud Console.

الردّ على إجراء رسالة

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

Node.js

/**
 * 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 handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  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.message.text;

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

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

/**
 * 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.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.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_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.
    metadata = event.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 = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "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 handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.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 = event.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);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

استبدِل REMIND_ME_COMMAND_ID برقم تعريف الأمر الذي حدّدته عند ضبط الأمر في Google Cloud Console.

اختبار الأمر

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

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

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

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

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

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

Node.js

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

Python

جافا

إعداد الأمر

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

لتسمية أمر:

لوصف أمر:

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

الردّ على أمر

الردّ على أمر يبدأ بشرطة مائلة

Node.js

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

Python

جافا

الردّ على أمر سريع

Node.js

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

Python

جافا

الردّ على إجراء رسالة

Node.js

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

Python

جافا

اختبار الأمر

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

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