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

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

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

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

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

شما می‌توانید دستورات برنامه چت را به صورت دستورات اسلش یا دستورات سریع بسازید. برای کشف دستورات، کاربران می‌توانند در قسمت پاسخ یک اسلش / تایپ کنند یا روی ابزارهای Google Workspace کلیک کنند. از قسمت پاسخ یک پیام چت. برای استفاده از هر نوع دستور، کاربران می‌توانند موارد زیر را انجام دهند:

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

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

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

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

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

پیش‌نیازها

اچ‌تی‌پی

یک افزونه‌ی Google Workspace که Google Chat را توسعه می‌دهد. برای ساخت آن، راهنمای سریع HTTP را تکمیل کنید.

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

یک افزونه‌ی Google Workspace که Google Chat را توسعه می‌دهد. برای ساخت آن، راهنمای سریع Apps Script را تکمیل کنید.

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

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

  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، مراحل زیر را انجام دهید: o برای پیکربندی یک دستور اسلش در Google Chat API، مراحل زیر را انجام دهید:

  1. در کنسول گوگل کلود، روی منو > 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 مشخص کرده‌اید، ارسال می‌شود.

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

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

نود جی اس 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = ABOUT_COMMAND_ID;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

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

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = ABOUT_COMMAND_ID;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (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 مشخص کرده‌اید، جایگزین کنید.

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

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

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