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

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

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

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

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

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

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

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

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

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

پیش‌نیازها

نود جی اس

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

اسکریپت برنامه‌ها

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی در Apps Script، این راهنمای سریع را تکمیل کنید.

پایتون

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

جاوا

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

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

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

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

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

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

نام و توضیحات دستور Slash
نام و توضیحات برای یک دستور اسلش.

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

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

  • از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات برای کاربر واضح باشند. برای مثال، به جای نام 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. در کنسول گوگل کلود، روی منو > APIها و خدمات > APIها و خدمات فعال‌شده > Google Chat API کلیک کنید.

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

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

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

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

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

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

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

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

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

پیام خصوصی برای اپلیکیشن چت Cymbal Labs. این پیام می‌گوید که اپلیکیشن چت توسط Cymbal Labs ساخته شده و لینکی به مستندات و لینکی برای تماس با تیم پشتیبانی به اشتراک گذاشته است.
یک برنامه چت به صورت خصوصی به دستور اسلش /help پاسخ می‌دهد تا نحوه دریافت پشتیبانی را توضیح دهد.

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

نوع فرمان نوع رویداد فراداده‌های فرمان
دستور اسلش MESSAGE message.slashCommand یا message.annotation.slashCommand
دستور سریع APP_COMMAND appCommandMetadata

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

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

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

نود جی اس

گره/avatar-app/index.js
/**
 * 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
// 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.'
      };
  }
}

پایتون

پایتون/avatar-app/main.py
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
/**
 * 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 را مدیریت می‌کند، تشخیص می‌دهد که آیا رویداد تعاملی حاوی شناسه دستور منطبق است یا خیر، و یک پیام خصوصی برمی‌گرداند:

نود جی اس

گره/avatar-app/index.js
/**
 * 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
/**
 * 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.'
      };
  }
}

پایتون

پایتون/avatar-app/main.py
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
/**
 * 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 مشخص کرده‌اید، جایگزین کنید.

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

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

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

،

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

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

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

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

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

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

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

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

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

پیش‌نیازها

نود جی اس

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

اسکریپت برنامه‌ها

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی در Apps Script، این راهنمای سریع را تکمیل کنید.

پایتون

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

جاوا

یک برنامه چت گوگل که رویدادهای تعاملی را دریافت و به آنها پاسخ می‌دهد. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این راهنمای سریع را تکمیل کنید.

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

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

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

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

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

نام و توضیحات دستور Slash
نام و توضیحات برای یک دستور اسلش.

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

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

  • از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات برای کاربر واضح باشند. برای مثال، به جای نام 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. در کنسول گوگل کلود، روی منو > APIها و خدمات > APIها و خدمات فعال‌شده > Google Chat API کلیک کنید.

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

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

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

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

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

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

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

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

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

پیام خصوصی برای اپلیکیشن چت Cymbal Labs. این پیام می‌گوید که اپلیکیشن چت توسط Cymbal Labs ساخته شده و لینکی به مستندات و لینکی برای تماس با تیم پشتیبانی به اشتراک گذاشته است.
یک برنامه چت به صورت خصوصی به دستور اسلش /help پاسخ می‌دهد تا نحوه دریافت پشتیبانی را توضیح دهد.

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

نوع فرمان نوع رویداد فراداده‌های فرمان
دستور اسلش MESSAGE message.slashCommand یا message.annotation.slashCommand
دستور سریع APP_COMMAND appCommandMetadata

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

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

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

نود جی اس

گره/avatar-app/index.js
/**
 * 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
// 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.'
      };
  }
}

پایتون

پایتون/avatar-app/main.py
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
/**
 * 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 را مدیریت می‌کند، تشخیص می‌دهد که آیا رویداد تعاملی حاوی شناسه دستور منطبق است یا خیر، و یک پیام خصوصی برمی‌گرداند:

نود جی اس

گره/avatar-app/index.js
/**
 * 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
/**
 * 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.'
      };
  }
}

پایتون

پایتون/avatar-app/main.py
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
/**
 * 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 مشخص کرده‌اید، جایگزین کنید.

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

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

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