به دستورات برنامه 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. در قسمت دستورات ، روی افزودن یک دستور کلیک کنید.

4. شناسه فرمان، توضیحات، نوع فرمان و نام آن را وارد کنید:

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

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

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

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

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

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

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

برای پاسخ به هر نوع دستور، باید انواع مختلف رویداد و اشیاء فراداده را در payload رویداد مدیریت کنید:

برای یادگیری نحوه پاسخ به یک فرمان با یک پیام، به بخش‌های زیر مراجعه کنید.

پاسخ به یک دستور اسلش

کد زیر نمونه‌ای از یک برنامه‌ی چت را نشان می‌دهد که به دستور اسلش /about پاسخ می‌دهد. برنامه‌ی چت رویدادهای تعاملی MESSAGE مدیریت می‌کند، تشخیص می‌دهد که آیا رویداد تعاملی حاوی شناسه‌ی دستور منطبق است یا خیر، و یک پیام خصوصی برمی‌گرداند:

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

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

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

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

پاسخ سریع به یک دستور

کد زیر نمونه‌ای از یک برنامه چت را نشان می‌دهد که به دستور سریع Help پاسخ می‌دهد. برنامه چت رویدادهای تعاملی APP_COMMAND را مدیریت می‌کند، تشخیص می‌دهد که آیا رویداد تعاملی حاوی شناسه دستور منطبق است یا خیر، و یک پیام خصوصی برمی‌گرداند:

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

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

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

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

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

کد زیر نمونه‌ای از یک برنامه چت را نشان می‌دهد که به اکشن پیام Remind me پاسخ می‌دهد. برنامه چت رویدادهای تعاملی APP_COMMAND را مدیریت می‌کند، تشخیص می‌دهد که آیا رویداد تعاملی حاوی شناسه دستور منطبق است یا خیر، و یک پیام خصوصی برمی‌گرداند:

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

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

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

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

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

مباحث مرتبط

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