به دستورات برنامه Google Chat پاسخ دهید

این صفحه نحوه تنظیم و پاسخ به دستورات به عنوان یک برنامه چت گوگل را توضیح می‌دهد.

دستورات به کاربران کمک می‌کنند تا ویژگی‌های کلیدی یک برنامه چت را کشف و استفاده کنند. فقط برنامه‌های چت می‌توانند محتوای یک دستور را ببینند. به عنوان مثال، اگر کاربری پیامی با دستور اسلش ارسال کند، آن پیام فقط برای کاربر و برنامه چت قابل مشاهده است.

برای تصمیم‌گیری در مورد اینکه آیا باید دستوراتی بسازید یا خیر، و برای درک نحوه طراحی تعاملات کاربر، به بخش «تعریف همه مسیرهای کاربر» مراجعه کنید.

انواع دستورات برنامه چت

1. دستورات اسلش: ​​کاربران می‌توانند یک دستور اسلش را از منو انتخاب کنند یا یک اسلش ( / ) و سپس یک متن از پیش تعریف شده، مانند /about تایپ کنند. برنامه‌های چت معمولاً برای دستور اسلش به متن آرگومان نیاز دارند.

   اگر برنامه چت شما به ورودی اضافی از کاربر نیاز دارد، یک دستور اسلش ایجاد کنید. برای مثال، می‌توانید یک دستور اسلش به نام /search ایجاد کنید که پس از وارد کردن عبارتی برای جستجو توسط کاربر، مانند /search receipts ، اجرا شود.

2. دستورات سریع: کاربران با باز کردن منو از قسمت پاسخ یک پیام چت، از دستورات استفاده می‌کنند. برای استفاده از یک دستور، روی افزودن کلیک می‌کنند. و یک دستور را از منو انتخاب کنید.

   اگر برنامه چت شما می‌تواند بلافاصله و بدون انتظار برای ورودی اضافی به کاربر پاسخ دهد، یک دستور سریع ایجاد کنید. برای مثال، می‌توانید یک دستور سریع به نام تصویر تصادفی ایجاد کنید که بلافاصله با یک تصویر پاسخ می‌دهد.

3. اقدامات پیام: ( پیش‌نمایش توسعه‌دهندگان science ) کاربران با نگه داشتن ماوس روی یک پیام و کلیک روی منوی سه نقطه از اقدامات پیام استفاده می‌کنند. برای استفاده از یک دستور، منوی سه نقطه را باز می‌کنند و یک دستور را از منو انتخاب می‌کنند.

   اگر برنامه چت شما می‌تواند بر اساس متن یک پیام، اقداماتی انجام دهد، یک اقدام پیام ایجاد کنید.

تصاویر زیر نشان می‌دهند که کاربران چگونه منوی مربوط به دستورات اسلش و سریع و اقدامات مربوط به پیام را پیدا می‌کنند:

پیش‌نیازها

فرمان را تنظیم کنید

این بخش نحوه انجام مراحل زیر را برای تنظیم یک فرمان توضیح می‌دهد:

1. یک نام و توضیح برای دستور ایجاد کنید .
2. دستور را در کنسول Google Cloud پیکربندی کنید .

نام و شرح دستور

نام یک دستور، چیزی است که کاربران برای فراخوانی برنامه چت تایپ یا انتخاب می‌کنند. توضیح کوتاهی نیز در زیر نام آن نمایش داده می‌شود تا کاربران را در مورد نحوه استفاده از دستور راهنمایی کند:

هنگام انتخاب نام و توضیحات برای دستور خود، توصیه‌های زیر را در نظر بگیرید:

برای نامگذاری یک دستور:

• از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات برای کاربر واضح باشند. برای مثال، به جای نام Create a reminder ، Remind me استفاده کنید.
• استفاده از یک نام منحصر به فرد یا رایج برای دستور خود را در نظر بگیرید. اگر دستور شما یک تعامل یا ویژگی معمولی را توصیف می‌کند، می‌توانید از یک نام رایج که کاربران آن را می‌شناسند و انتظار دارند، مانند Settings یا Feedback ، استفاده کنید. در غیر این صورت، سعی کنید از نام‌های دستور منحصر به فرد استفاده کنید، زیرا اگر نام دستور شما برای سایر برنامه‌های چت یکسان باشد، کاربر باید دستورات مشابه را فیلتر کند تا دستور شما را پیدا کرده و از آن استفاده کند.

برای توصیف یک دستور:

• توضیحات را کوتاه و واضح نگه دارید تا کاربران بدانند هنگام استفاده از دستور چه انتظاری داشته باشند.
• اگر الزامات قالب‌بندی برای دستور وجود دارد، به کاربران اطلاع دهید. برای مثال، اگر یک دستور اسلش ایجاد می‌کنید که به متن آرگومان نیاز دارد، توضیحات را روی چیزی مانند Remind me to do [something] at [time] تنظیم کنید.
• به کاربران اطلاع دهید که آیا برنامه چت به همه افراد حاضر در فضا پاسخ می‌دهد یا به صورت خصوصی به کاربری که دستور را فراخوانی می‌کند. به عنوان مثال، برای دستور سریع About »، می‌توانید آن را به صورت Learn about this app (Only visible to you) توصیف کنید.

دستور را در کنسول Google Cloud پیکربندی کنید

برای ایجاد یک دستور اسلش، دستور سریع یا اقدام پیام، شما اطلاعات مربوط به دستور یا اقدام را در پیکربندی برنامه چت خود برای Google Chat API مشخص می‌کنید.

برای پیکربندی یک دستور در Google Chat API، مراحل زیر را انجام دهید:

1. در کنسول گوگل کلود، روی menu منو > APIها و خدمات > APIها و خدمات فعال‌شده > Google Chat API کلیک کنید.

   به صفحه API چت گوگل بروید

2. روی پیکربندی کلیک کنید.

3. در قسمت تنظیمات اتصال (Connection settings )، به بخش محرک‌ها (Triggers) بروید و جزئیات نقطه پایانی خود را مشخص کنید. برای پاسخ به دستور، باید از این محرک در بخش بعدی استفاده کنید.

   1. آدرس اینترنتی نقطه پایانی HTTP : می‌توانید یک آدرس اینترنتی نقطه پایانی HTTP مشترک را در اینجا مشخص کنید. به طور جایگزین، برای استفاده از نقاط پایانی HTTP مختلف برای تریگرهای مختلف، نقطه پایانی را مستقیماً در فیلد دستور App مشخص کنید.
   2. Apps Script : شناسه‌ی استقرار Apps Script را وارد کنید. به طور پیش‌فرض، تابع onAppCommand فراخوانی می‌شود. برای استفاده از یک تابع Apps Script متفاوت، نام تابع سفارشی را در فیلد دستور App مشخص کنید.

4. در قسمت دستورات ، روی افزودن یک دستور کلیک کنید.

5. اطلاعات زیر را در مورد دستور وارد کنید:

   1. شناسه فرمان: عددی از ۱ تا ۱۰۰۰ که برنامه چت شما برای تشخیص فرمان و بازگرداندن پاسخ از آن استفاده می‌کند.
   2. توضیحات: متنی که نحوه استفاده و قالب‌بندی دستور را شرح می‌دهد. توضیحات می‌توانند تا ۵۰ کاراکتر باشند.
   3. نوع دستور: یکی از گزینه‌های دستور سریع ، دستور اسلش یا اقدام پیام‌رسان را انتخاب کنید.
   4. برای دستور یک نام مشخص کنید:
      • نام دستور سریع: نام نمایشی که کاربران از منو برای فراخوانی دستور انتخاب می‌کنند. می‌تواند تا ۵۰ کاراکتر باشد و شامل کاراکترهای ویژه باشد. برای مثال، Remind me .
      • نام دستور اسلش: ​​متنی که کاربران برای فراخوانی دستور در یک پیام تایپ می‌کنند. باید با یک اسلش شروع شود، فقط شامل متن باشد و می‌تواند تا ۵۰ کاراکتر باشد. برای مثال، /remindMe .
      • نام عملیات پیام: (پیش‌نمایش توسعه‌دهنده science ) نام نمایشی که کاربران از منو برای فراخوانی عملیات پیام انتخاب می‌کنند. می‌تواند تا ۵۰ کاراکتر باشد و شامل کاراکترهای خاص باشد. برای مثال، Remind me .

6. اختیاری: بارگذاری پیام اعلان : (پیش‌نمایش توسعه‌دهنده science ) یک پیام اعلان آزمایشی برای نمایش به کاربر هنگام اجرای عملیات پیام. فقط برای عملیات پیامی که کادرهای محاوره‌ای را باز نمی‌کنند، در دسترس است.

7. اختیاری: اگر می‌خواهید برنامه چت شما با یک کادر محاوره‌ای به دستور پاسخ دهد، کادر انتخاب «باز کردن یک کادر محاوره‌ای» را علامت بزنید.

8. روی ذخیره کلیک کنید.

اکنون دستور برای برنامه چت پیکربندی شده است.

پاسخ به یک فرمان

وقتی کاربران از یک دستور استفاده می‌کنند، برنامه چت شما یک شیء رویداد دریافت می‌کند. این رویداد شامل یک شیء appCommandPayload با جزئیاتی در مورد دستوری که فراخوانی شده است (از جمله شناسه دستور و نوع دستور) است، به طوری که بتوانید پاسخ مناسبی را برگردانید. شیء رویداد به نقطه پایانی HTTP یا تابع Apps Script که هنگام پیکربندی تریگر دستور App مشخص کرده‌اید، ارسال می‌شود.

کد زیر نمونه‌ای از یک برنامه چت را نشان می‌دهد که به دستور اسلش /about با یک پیام متنی پاسخ می‌دهد. برای پاسخ به دستورات اسلش، برنامه چت اشیاء رویداد را از یک تریگر دستور App مدیریت می‌کند. هنگامی که payload یک شیء رویداد حاوی شناسه دستور اسلش باشد، برنامه چت اکشن 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 مشخص کرده‌اید، جایگزین کنید.

پاسخ به یک پیام

کد زیر نمونه‌ای از یک برنامه چت را نشان می‌دهد که به اکشن پیام «با یک پیام متنی به من یادآوری کن » پاسخ می‌دهد. برای پاسخ به اکشن‌های پیام، برنامه چت اشیاء رویداد را از یک تریگر دستور App مدیریت می‌کند. هنگامی که payload یک شیء رویداد شامل شناسه دستور action پیام باشد، برنامه چت اکشن DataActions را با یک شیء createMessageAction برمی‌گرداند:

/**
 * 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 مشخص کرده‌اید، جایگزین کنید.

دستور را آزمایش کنید

برای آزمایش دستور و کد، به بخش «آزمایش ویژگی‌های تعاملی برای برنامه‌های چت گوگل» مراجعه کنید.

برای آشنایی با نحوه آزمایش و استفاده از این دستور در رابط کاربری چت، به بخش «استفاده از برنامه‌ها در گوگل چت» در مستندات راهنمای گوگل چت مراجعه کنید.

مباحث مرتبط

• مشاهده نمونه‌های برنامه چت که از دستورات استفاده می‌کنند
• ارسال پیام
• باز کردن پنجره‌های محاوره‌ای تعاملی