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

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

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

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

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

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

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

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

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

پیش‌نیازها

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

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

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، مراحل زیر را انجام دهید: o برای پیکربندی یک دستور اسلش در 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. نوع دستور: یکی از دو دستور Quick یا Slash را انتخاب کنید.
   4. یک نام برای دستور quick یا دستور slash مشخص کنید:
      • نام دستور سریع: نام نمایشی که کاربران از منو برای فراخوانی دستور انتخاب می‌کنند. می‌تواند تا ۵۰ کاراکتر باشد و شامل کاراکترهای ویژه باشد. برای مثال، Remind me .
      • نام دستور اسلش: ​​متنی که کاربران برای فراخوانی دستور در یک پیام تایپ می‌کنند. باید با یک اسلش شروع شود، فقط شامل متن باشد و می‌تواند تا ۵۰ کاراکتر باشد. برای مثال، /remindMe .

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

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

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

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

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

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

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

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

مباحث مرتبط

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