این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

این صفحه نحوه پیکربندی یک برنامه Google Chat را برای پاسخ به دستورات اسلش توضیح می‌دهد.

در Google Chat، افزونه‌ها به عنوان برنامه‌های Google Chat برای کاربران ظاهر می‌شوند. برای کسب اطلاعات بیشتر، به نمای کلی Extend Google Chat مراجعه کنید.

دستور اسلش روشی متداول است که کاربران با آن برنامه چت را فراخوانی کرده و با آن تعامل دارند. دستورات اسلش همچنین به کاربران کمک می کند تا ویژگی های کلیدی یک برنامه چت را کشف کرده و از آنها استفاده کنند. برای تصمیم گیری در مورد اینکه آیا باید دستورات اسلش را تنظیم کنید یا نه و برای درک نحوه طراحی تعاملات کاربر، به تعریف همه سفرهای کاربر در اسناد Chat API مراجعه کنید.

نحوه استفاده کاربران از دستورات اسلش

برای استفاده از دستور اسلش، کاربران یک اسلش ( / ) و سپس یک دستور متن کوتاه مانند /about را تایپ می کنند تا اطلاعاتی در مورد برنامه چت دریافت کنند. کاربران می توانند با تایپ یک اسلش در Google Chat، دستورات اسلش موجود را پیدا کنند، که پنجره ای را نشان می دهد که دستورات موجود برای برنامه Chat را فهرست می کند:

اسلش پنجره فرمان — **شکل 1** : پنجره ای که وقتی کاربران یک اسلش در چت گوگل تایپ می کنند ظاهر می شود.

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

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

پیش نیازها

Node.js

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

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

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

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

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

یک نام برای دستور اسلش خود ایجاد کنید .
دستور اسلش را در Google Chat API پیکربندی کنید .

دستور اسلش خود را نام ببرید

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

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

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

برای نامگذاری دستور اسلش:
- از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات برای کاربر واضح و ساده باشد. به عنوان مثال، به جای گفتن /createAReminder ، از /remindMe استفاده کنید.
- اگر دستور شما حاوی بیش از یک کلمه است، با استفاده از تمام حروف کوچک برای کلمه اول و سپس بزرگ کردن حرف اول کلمات اضافی به کاربران کمک کنید دستور را بخوانند. به عنوان مثال، به جای /updatecontact ، از /updateContact استفاده کنید.
- در نظر بگیرید که آیا از یک نام منحصر به فرد یا معمول برای دستور خود استفاده کنید. اگر دستور شما یک تعامل یا ویژگی معمولی را توصیف می‌کند، می‌توانید از نام مشترکی استفاده کنید که کاربران آن را تشخیص می‌دهند و انتظار دارند، مانند /settings یا /feedback . در غیر این صورت، سعی کنید از نام‌های دستوری منحصربه‌فرد استفاده کنید، زیرا اگر نام دستور شما برای سایر برنامه‌های چت یکسان است، کاربر باید دستورات مشابه را برای یافتن و استفاده از دستورات شما فیلتر کند.
برای توصیف دستور اسلش:
- توضیحات را کوتاه و واضح نگه دارید تا کاربران بدانند هنگام فراخوانی دستور چه انتظاری داشته باشند.
- به کاربران اطلاع دهید که آیا الزامات قالب بندی برای دستور وجود دارد. برای مثال، اگر یک دستور /remindMe ایجاد می‌کنید که به متن آرگومان نیاز دارد، توضیحات را روی چیزی مانند Remind me to do [something] at [time] تنظیم کنید.
- به کاربران اطلاع دهید که آیا برنامه چت به همه افراد حاضر در فضا پاسخ می دهد یا به صورت خصوصی به کاربری که این فرمان را فراخوانی می کند. برای مثال، برای دستور اسلش /about ، می‌توانید آن را با عنوان Learn about this app (Only visible to you) توصیف کنید.

دستور اسلش خود را در Google Chat API پیکربندی کنید

برای ایجاد یک دستور اسلش، باید اطلاعات مربوط به فرمان را در پیکربندی برنامه چت خود برای Google Chat API مشخص کنید.

برای پیکربندی یک دستور اسلش در Google Chat API، مراحل زیر را انجام دهید:

در کنسول Google Cloud، روی > APIs & Services > Enabled APIs & Services > Google Chat API کلیک کنید.
به صفحه Google Chat API بروید
روی پیکربندی کلیک کنید.
در قسمت تنظیمات پیشرفته ، به Triggers بروید و بررسی کنید که فیلد دستور App حاوی یک ماشه باشد، مانند یک نقطه پایانی HTTP یا عملکرد Apps Script. برای پاسخ به دستور اسلش باید از این trigger to در قسمت زیر استفاده کنید.
در بخش Commands ، روی Add a command کلیک کنید.
شناسه فرمان، نوع فرمان، نام دستور اسلش، نام و توضیحات دستور را وارد کنید:
1. شناسه فرمان: عددی از 1 تا 1000 که برنامه چت شما از آن برای تشخیص دستور اسلش و برگرداندن پاسخ استفاده می کند.
2. نوع فرمان: دستور Slash را انتخاب کنید.
3. نام دستور اسلش: نام نمایشی دستور و آنچه کاربران برای فراخوانی برنامه شما تایپ می کنند. باید با اسلش شروع شود، فقط حاوی متن باشد و حداکثر 50 کاراکتر باشد.
4. نام: نام کاربر پسند دستور. نام ها می توانند حداکثر 50 کاراکتر باشند و می توانند شامل کاراکترهای خاص باشند.
  - از کلمات یا عبارات کوتاه، توصیفی و کاربردی استفاده کنید تا دستورات را برای کاربر واضح کنید. به عنوان مثال، از Update contact برای دستوری که رکورد مخاطب را تغییر می دهد، استفاده کنید.
5. توضیحات: متنی که نحوه استفاده و قالب بندی دستور را توضیح می دهد. توضیحات می تواند حداکثر 50 کاراکتر باشد.
اختیاری: اگر می‌خواهید برنامه چت شما به فرمان با یک گفتگو پاسخ دهد، کادر باز کردن یک گفتگو را انتخاب کنید.
روی ذخیره کلیک کنید.

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

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

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

برای پاسخ به یک دستور اسلش، باید راه‌انداز دستور App را اجرا کنید تا برنامه چت شما بتواند هر شی رویدادی را که حاوی فراداده دستور برنامه است کنترل کند.

پیام خصوصی برای برنامه چت Cymbal Labs. پیام می گوید که برنامه چت توسط Cymbal Labs ایجاد شده است و پیوندی را به اشتراک می گذارد به مستندات و پیوندی برای تماس با تیم پشتیبانی. — یک برنامه چت به صورت خصوصی به دستور اسلش `/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 APP_COMMAND events
    if (chatEvent.appCommandPayload) {

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

        if (appCommandMetadata.appCommandType === "SLASH_COMMAND") {
            // 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;

    if (appCommandMetadata.appCommandType == "SLASH_COMMAND") {

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