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

پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند.

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

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

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

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

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

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

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

• 

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

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

پیش نیازها

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

• یک حساب Google Workspace تجاری یا سازمانی با دسترسی به Google Chat .
• یک پروژه Google Cloud ایجاد کنید .
• صفحه رضایت OAuth را پیکربندی کنید .
• APIهای Google Workspace زیر را فعال کنید :
  • Google Chat API
  • API افزونه‌های Google Workspace
    نمی‌توانید از API افزونه‌های Google Workspace برای ایجاد و مدیریت استقرار برنامه Chat استفاده کنید. برای جزئیات، محدودیت ها و مسائل شناخته شده را ببینید.
• یک نقطه پایانی HTTP که معماری سرویس را برای برنامه چت شما میزبانی می کند.

• یک حساب Google Workspace تجاری یا سازمانی با دسترسی به Google Chat .
• یک پروژه Google Cloud ایجاد کنید .
• صفحه رضایت OAuth را پیکربندی کنید .
• Google Chat API را فعال کنید .
• یک پروژه Apps Script مستقل ایجاد کنید و سرویس گفتگوی پیشرفته را روشن کنید.
• با افزودن شی addons.chat و هر حوزه مورد نیاز ( oauthScopes ) یا پیشوندهای URL HTTPS ( urlFetchWhitelist ) Chat را در مانیفست پیکربندی کنید .

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

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

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

1. در کنسول Google Cloud، > APIs & Services > Enabled APIs & Services > Google Chat API کلیک کنید.

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

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

3. در قسمت تنظیمات پیشرفته ، به Triggers بروید و بررسی کنید که فیلد دستور App حاوی یک ماشه باشد، مانند یک نقطه پایانی HTTP یا عملکرد Apps Script. برای پاسخ دادن به دستور باید از این ماشه در قسمت زیر استفاده کنید.

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

5. اطلاعات زیر را در مورد دستور وارد کنید:

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

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

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

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

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

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

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

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

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

// 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 = 0;

/**
 * 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 = 0;

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

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

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

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

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

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