Отвечайте на команды с косой чертой в Google Chat

На этой странице объясняется, как настроить приложение Google Chat для ответа на команды с косой чертой.

В Google Chat дополнения отображаются пользователям как приложения Google Chat. Дополнительную информацию см. в обзоре расширения Google Chat .

Команда косой черты — это распространенный способ вызова приложения чата и взаимодействия с ним. Слэш-команды также помогают пользователям находить и использовать ключевые функции приложения чата. Чтобы решить, следует ли вам настраивать команды с косой чертой, а также понять, как проектировать взаимодействие с пользователем, см. раздел «Определение всех циклов взаимодействия пользователя» в документации Chat API.

Как пользователи используют команды слэша

Чтобы использовать команду с косой чертой, пользователи вводят косую черту ( / ), а затем короткую текстовую команду, например /about чтобы получить информацию о приложении Chat. Пользователи могут найти доступные команды с косой чертой, введя косую черту в Google Chat, после чего откроется окно со списком доступных команд для приложения Chat:

Окно команды слэша
Рис. 1. Окно, которое появляется, когда пользователи вводят косую черту в Google Chat.

Когда пользователь отправляет сообщение, содержащее косую черту, это сообщение видно только пользователю и приложению Chat. Если вы настроили приложение чата для добавления в пространства с несколькими людьми, вы можете рассмотреть возможность ответа на команду косой черты конфиденциально, чтобы сохранить конфиденциальность взаимодействия между пользователем и приложением чата.

Например, чтобы узнать о приложении Chat, обнаруженном в пространстве, пользователи могут использовать такие команды, как /about или /help . Чтобы не уведомлять всех остальных в этом пространстве, приложение Chat может ответить конфиденциально, предоставив информацию о том, как использовать приложение Chat и получить поддержку.

Предварительные условия

Node.js

Надстройка Google Workspace, расширяющая Google Chat. Чтобы создать его, выполните краткое руководство по HTTP .

Скрипт приложений

Надстройка Google Workspace, расширяющая Google Chat. Чтобы создать его, выполните краткое руководство по Apps Script .

Настройте команду косой черты

В этом разделе объясняется, как выполнить следующие шаги для настройки команды косой черты:

  1. Создайте имя для своей косой черты.
  2. Настройте команду косой черты в API Google Chat.

Назовите свою косую черту

Имя команды с косой чертой — это то, что пользователи вводят в сообщении чата для вызова приложения чата. Под именем также отображается краткое описание, подсказывающее пользователям, как использовать команду:

Название и описание команды слэш
Рисунок 2 : Имя и описание косой черты.

При выборе имени и описания для вашей косой черты примите во внимание следующие рекомендации:

  • Чтобы назвать вашу косую черту:

    • Используйте короткие, описательные и действенные слова или фразы, чтобы сделать команды понятными и простыми для пользователя. Например, вместо /createAReminder используйте /remindMe .
    • Если ваша команда содержит более одного слова, помогите пользователям прочитать команду, используя все строчные буквы для первого слова, а затем заглавную первую букву дополнительных слов. Например, вместо /updatecontact используйте /updateContact .
    • Подумайте, использовать ли для вашей команды уникальное или общее имя. Если ваша команда описывает типичное взаимодействие или функцию, вы можете использовать общее имя, которое пользователи узнают и ожидают, например /settings или /feedback . В противном случае попробуйте использовать уникальные имена команд, поскольку, если имя вашей команды одинаково для других приложений чата, пользователю придется фильтровать похожие команды, чтобы найти и использовать вашу.

  • Чтобы описать вашу косую черту:

    • Описание должно быть кратким и понятным, чтобы пользователи знали, чего ожидать при вызове команды.
    • Сообщите пользователям, есть ли какие-либо требования к форматированию команды. Например, если вы создаете команду /remindMe , для которой требуется текст аргумента, установите для описания что-то вроде Remind me to do [something] at [time] .
    • Сообщите пользователям, отвечает ли приложение Chat всем в группе или лично пользователю, который вызывает команду. Например, команду /about можно описать как Learn about this app (Only visible to you) .

Настройте свою косую черту в API Google Chat

Чтобы создать косую черту, вам необходимо указать информацию о команде в конфигурации вашего приложения Chat для API Google Chat.

Чтобы настроить косую черту в API Google Chat, выполните следующие действия:

  1. В консоли Google Cloud нажмите > API и службы > Включенные API и службы > Google Chat API.

    Перейдите на страницу API Google Chat.

  2. Нажмите Конфигурация .

  3. В разделе «Дополнительные настройки » перейдите в раздел «Триггеры» и убедитесь, что поле «СООБЩЕНИЕ» содержит триггер, например конечную точку HTTP или функцию скрипта приложений. Вы должны использовать этот триггер, чтобы в следующем разделе ответить на команду косой черты.

  4. В разделе «Команды косой черты» нажмите «Добавить команду косой черты» .

  5. Введите имя, идентификатор команды и описание команды:

    1. Имя: отображаемое имя команды и вводимый пользователем текст для вызова вашего приложения. Должно начинаться с косой черты, содержать только текст и может содержать до 50 символов.
    2. Описание: текст, описывающий, как использовать и форматировать команду. Описания могут содержать до 50 символов.
    3. Идентификатор команды: число от 1 до 1000, которое ваше приложение Chat использует для распознавания команды косой черты и возврата ответа.

  6. Необязательно: если вы хотите, чтобы приложение Chat отвечало на команду диалоговым окном, установите флажок Открыть диалоговое окно.

  7. Нажмите Сохранить .

Команда косой черты теперь настроена для приложения Chat.

Ответ на команду косой черты

Когда пользователи создают сообщение чата, ваше приложение чата получает объект события, содержащий информацию о сообщении. Объект события содержит полезную информацию с подробной информацией о команде, использованной в сообщении (включая идентификатор команды), чтобы вы могли вернуть соответствующий ответ.

Чтобы ответить на команду косой черты, необходимо реализовать триггер «Сообщение» , чтобы ваше приложение чата могло обрабатывать любые объекты событий , содержащие метаданные команды косой черты.

Личное сообщение для Приложение Cymbal Labs Chat. В сообщении говорится, что Приложение чата было создано Cymbal Labs и содержит ссылку к документации и ссылку для связи со службой поддержки.
Приложение чата отвечает в частном порядке на команду косой черты /help , чтобы объяснить, как получить поддержку.

В следующем коде показан пример приложения Chat, которое отвечает на команду косой черты /about текстовым сообщением. Чтобы реагировать на команды с косой чертой, приложение «Чат» обрабатывает объекты событий из триггера «Сообщение» . Если полезные данные объекта события содержат идентификатор команды с косой чертой, приложение 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

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

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

Чтобы использовать этот пример кода, замените ABOUT_COMMAND_ID идентификатором команды, который вы указали при настройке команды косой черты в Chat API .

,

На этой странице объясняется, как настроить приложение Google Chat для ответа на команды с косой чертой.

В Google Chat дополнения отображаются пользователям как приложения Google Chat. Дополнительную информацию см. в обзоре расширения Google Chat .

Команда косой черты — это распространенный способ вызова приложения чата и взаимодействия с ним. Слэш-команды также помогают пользователям находить и использовать ключевые функции приложения чата. Чтобы решить, следует ли вам настраивать команды с косой чертой, а также понять, как проектировать взаимодействие с пользователем, см. раздел «Определение всех циклов взаимодействия пользователя» в документации Chat API.

Как пользователи используют команды слэша

Чтобы использовать команду с косой чертой, пользователи вводят косую черту ( / ), а затем короткую текстовую команду, например /about чтобы получить информацию о приложении Chat. Пользователи могут найти доступные команды с косой чертой, введя косую черту в Google Chat, после чего откроется окно со списком доступных команд для приложения Chat:

Окно команды слэша
Рис. 1. Окно, которое появляется, когда пользователи вводят косую черту в Google Chat.

Когда пользователь отправляет сообщение, содержащее косую черту, это сообщение видно только пользователю и приложению Chat. Если вы настроили приложение чата для добавления в пространства с несколькими людьми, вы можете рассмотреть возможность ответа на косую черту в частном порядке, чтобы сохранить конфиденциальность взаимодействия между пользователем и приложением чата.

Например, чтобы узнать о приложении Chat, обнаруженном в пространстве, пользователи могут использовать такие команды, как /about или /help . Чтобы не уведомлять всех остальных в этом пространстве, приложение Chat может ответить конфиденциально, предоставив информацию о том, как использовать приложение Chat и получить поддержку.

Предварительные условия

Node.js

Надстройка Google Workspace, расширяющая Google Chat. Чтобы создать его, выполните краткое руководство по HTTP .

Скрипт приложений

Надстройка Google Workspace, расширяющая Google Chat. Чтобы создать его, выполните краткое руководство по Apps Script .

Настройте команду косой черты

В этом разделе объясняется, как выполнить следующие шаги для настройки команды косой черты:

  1. Создайте имя для своей косой черты.
  2. Настройте команду косой черты в API Google Chat.

Назовите свою косую черту

Имя команды с косой чертой — это то, что пользователи вводят в сообщении чата для вызова приложения чата. Под именем также отображается краткое описание, подсказывающее пользователям, как использовать команду:

Название и описание команды слэш
Рисунок 2. Имя и описание косой черты.

При выборе имени и описания для вашей косой черты примите во внимание следующие рекомендации:

  • Чтобы назвать вашу косую черту:

    • Используйте короткие, описательные и действенные слова или фразы, чтобы сделать команды понятными и простыми для пользователя. Например, вместо /createAReminder используйте /remindMe .
    • Если ваша команда содержит более одного слова, помогите пользователям прочитать команду, используя все строчные буквы для первого слова, а затем заглавную первую букву дополнительных слов. Например, вместо /updatecontact используйте /updateContact .
    • Подумайте, использовать ли для вашей команды уникальное или общее имя. Если ваша команда описывает типичное взаимодействие или функцию, вы можете использовать общее имя, которое пользователи узнают и ожидают, например /settings или /feedback . В противном случае попробуйте использовать уникальные имена команд, поскольку, если имя вашей команды одинаково для других приложений чата, пользователю придется фильтровать похожие команды, чтобы найти и использовать вашу.

  • Чтобы описать вашу косую черту:

    • Описание должно быть кратким и понятным, чтобы пользователи знали, чего ожидать при вызове команды.
    • Сообщите пользователям, есть ли какие-либо требования к форматированию команды. Например, если вы создаете команду /remindMe , для которой требуется текст аргумента, установите для описания что-то вроде Remind me to do [something] at [time] .
    • Сообщите пользователям, отвечает ли приложение Chat всем в группе или лично пользователю, который вызывает команду. Например, команду /about можно описать как Learn about this app (Only visible to you) .

Настройте свою косую черту в API Google Chat

Чтобы создать косую черту, вам необходимо указать информацию о команде в конфигурации вашего приложения Chat для Google Chat API.

Чтобы настроить косую черту в API Google Chat, выполните следующие действия:

  1. В консоли Google Cloud нажмите > API и службы > Включенные API и службы > Google Chat API.

    Перейдите на страницу API Google Chat.

  2. Нажмите Конфигурация .

  3. В разделе «Дополнительные настройки » перейдите в раздел «Триггеры» и убедитесь, что поле «СООБЩЕНИЕ» содержит триггер, например конечную точку HTTP или функцию скрипта приложений. Вы должны использовать этот триггер, чтобы в следующем разделе ответить на команду косой черты.

  4. В разделе «Команды косой черты» нажмите «Добавить команду косой черты» .

  5. Введите имя, идентификатор команды и описание команды:

    1. Имя: отображаемое имя команды и вводимый пользователем текст для вызова вашего приложения. Должно начинаться с косой черты, содержать только текст и может содержать до 50 символов.
    2. Описание: текст, описывающий, как использовать и форматировать команду. Описания могут содержать до 50 символов.
    3. Идентификатор команды: число от 1 до 1000, которое ваше приложение Chat использует для распознавания команды косой черты и возврата ответа.

  6. Необязательно: если вы хотите, чтобы приложение Chat отвечало на команду диалоговым окном, установите флажок Открыть диалоговое окно.

  7. Нажмите Сохранить .

Команда косой черты теперь настроена для приложения Chat.

Ответ на команду косой черты

Когда пользователи создают сообщение чата, ваше приложение чата получает объект события, содержащий информацию о сообщении. Объект события содержит полезные данные с подробной информацией о команде, использованной в сообщении (включая идентификатор команды), чтобы вы могли вернуть соответствующий ответ.

Чтобы ответить на команду косой черты, необходимо реализовать триггер «Сообщение» , чтобы ваше приложение чата могло обрабатывать любые объекты событий , содержащие метаданные команды косой черты.

Личное сообщение для Приложение Cymbal Labs Chat. В сообщении говорится, что Приложение чата было создано Cymbal Labs и содержит ссылку к документации и ссылку для связи со службой поддержки.
Приложение чата отвечает в частном порядке на команду косой черты /help , чтобы объяснить, как получить поддержку.

В следующем коде показан пример приложения Chat, которое отвечает на команду косой черты /about текстовым сообщением. Чтобы реагировать на команды с косой чертой, приложение «Чат» обрабатывает объекты событий из триггера «Сообщение» . Если полезные данные объекта события содержат идентификатор команды с косой чертой, приложение 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

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

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

Чтобы использовать этот пример кода, замените ABOUT_COMMAND_ID идентификатором команды, который вы указали при настройке команды косой черты в Chat API .