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

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

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

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

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

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

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

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

• 

  شکل 1. کاربران با تایپ یک اسلش / در ناحیه پاسخ و به دنبال آن نام دستور، دستورات اسلش را کشف و استفاده می کنند.

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

پیش نیازها

توجه: نمونه‌های کد موجود در این راهنما برای اجرا به‌عنوان یک تابع Google Cloud برای Node.js، Python و Java نوشته شده‌اند.

Node.js اسکریپت برنامه ها پایتون جاوا

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی در Apps Script، این شروع سریع را کامل کنید.

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

دستور را تنظیم کنید

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

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

دستور را نام ببرید و شرح دهید

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

شکل 3 : نام و توضیحات یک دستور اسلش.

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

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

• از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات را برای کاربر واضح کنید. به عنوان مثال، به جای نام 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. در کنسول Google Cloud، > APIs & Services > Enabled APIs & Services > Google Chat API کلیک کنید.

   به صفحه Google Chat API بروید

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

3. در بخش Commands ، روی Add a command کلیک کنید.

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

   • شناسه فرمان: عددی از 1 تا 1000 که برنامه چت شما از آن برای تشخیص فرمان و برگرداندن پاسخ استفاده می‌کند.
   • Name: نام نمایشی دستور. نام ها می توانند حداکثر 50 کاراکتر باشند و می توانند شامل کاراکترهای خاص باشند.
   • توضیحات: متنی که آنچه دستور انجام می دهد را توصیف می کند. توضیحات می تواند حداکثر 50 کاراکتر باشد و می تواند شامل کاراکترهای خاص باشد.
   • نوع فرمان: دستور Quick یا دستور Slash را انتخاب کنید.
   • اگر در حال پیکربندی یک دستور اسلش هستید، مقداری را برای فیلد نام دستور اسلش وارد کنید تا مشخص کنید کاربران چه چیزی را برای فراخوانی این فرمان تایپ می کنند. باید با اسلش شروع شود، فقط حاوی متن باشد و حداکثر 50 کاراکتر باشد. به عنوان مثال، /remindMe .

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

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

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

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

برای مثال‌های بیشتر، نمونه‌های برنامه Google Chat را ببینید.

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

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

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

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

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

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

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

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

کد زیر نمونه ای از یک برنامه چت را نشان می دهد که به فرمان سریع 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 مشاهده کنید

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

دستور را تست کنید

برای آزمایش فرمان و کد، به تست ویژگی‌های تعاملی برای برنامه‌های گپ Google مراجعه کنید.

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

موضوعات مرتبط

• نمونه‌های برنامه Chat را که از دستورات استفاده می‌کنند، مشاهده کنید
• ارسال پیام
• گفتگوهای تعاملی را باز کنید