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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTP

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

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

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

إعداد الأمر

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

أنشئ اسمًا ووصفًا للأمر.
ضبط الأمر في 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"، انقر على "القائمة" > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API.

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

تم الآن إعداد الأمر لتطبيق Chat.

ربط أوامر الخريطة بالاقتراحات الأوّلية

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

لربط أمر بطلب أوّلي:

تأكَّد من أنّ طلبك لا يتطلّب وسيطات مخصّصة إضافية (لا تتوفّر سوى الطلبات التي تتضمّن بدون وسيطات أو وسيطات أساسية كطلبات بدء).
في Google Cloud Console، انتقِل إلى صفحة الإعداد الخاصة بواجهة برمجة تطبيقات Chat.
ضمن الميزات التفاعلية > طلبات بدء المحادثة، انقروا على إضافة طلب.
اضبط الترتيب (من 1 إلى 3) لتحديد ترتيب العرض.
ضمن اختيار النوع، اختَر موجه الأوامر، ثم اختَر الأمر من القائمة المنسدلة.
انقر على تم، ثم انقر على حفظ.

الردّ على أمر

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

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

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

Node.js

node/chat/avatar-app/index.js

عرض على GitHub

// 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.'
      };
  }
}

Python

python/chat/avatar-app/main.py

عرض على GitHub

# 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 {}

جافا

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

عرض على GitHub

// 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;
  }
}

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

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

عرض على GitHub

// 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:

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 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}"`
            }
          }
        }
      }
    });
  }
}

Python

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 تستخدم الأوامر
إرسال رسالة
فتح مربّعات الحوار التفاعلية

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

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

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

HTTP

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

إعداد الأمر

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

لتسمية أمر، اتّبِع الخطوات التالية:

لوصف أمر:

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

ربط أوامر الخريطة بالاقتراحات الأوّلية

الردّ على أمر

Node.js

Python

جافا

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

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

Node.js

Python

جافا

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

اختبار الأمر

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

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