Эта страница переведена с помощью Cloud Translation API.

Отвечать на команды приложения Google Chat

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

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

Чтобы решить, следует ли создавать команды, а также понять, как проектировать взаимодействие с пользователем, см . раздел Определение всех циклов взаимодействия пользователя .

Типы команд приложения чата

Вы можете создавать команды приложения Chat в виде косой черты или быстрых команд. Чтобы обнаружить и использовать каждый тип команды, пользователи выполняют следующие действия:

Команды с косой чертой: пользователи отправляют команды в виде сообщений, вводя косую черту ( / ), а затем заранее заданный текст, например /about . Приложения чата также могут требовать текст аргумента для команды косой черты. Например, для команды /search может потребоваться текст аргумента, который используется для поискового запроса.
Быстрые команды: пользователи используют команды, открывая меню в области ответа на сообщение чата. Чтобы использовать команду, они нажимают кнопку «Добавить». и выберите команду из меню.

На следующих изображениях показано, как пользователи находят меню с косой чертой и быстрыми командами:

Рисунок 1. Пользователи находят и используют команды с косой чертой, вводя косую черту / в области ответа, а затем имя команды.
Рисунок 2. Пользователи находят и используют быстрые команды из меню в области ответа на сообщение чата.

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

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

Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
Создайте проект Google Cloud .
Настройте экран согласия OAuth .
Включите следующие API Google Workspace :
- API чата Google
- API надстроек Google Workspace
  Вы не можете использовать API надстроек Google Workspace для создания развертываний приложения Chat и управления ими. Подробности см. в разделе Ограничения и известные проблемы .
Конечная точка HTTP, в которой размещена архитектура службы для вашего приложения Chat.

Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
Создайте проект Google Cloud .
Настройте экран согласия OAuth .
Включите API Google Chat .
Создайте автономный проект Apps Script и включите расширенную службу чата .
Настройте Chat в манифесте , добавив объект addons.chat и все необходимые области ( oauthScopes ) или префиксы URL-адресов HTTPS ( urlFetchWhitelist ).

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

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

Создайте имя и описание для команды.
Настройте команду в консоли Google Cloud.

Назовите и опишите команду

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

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

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

Чтобы назвать команду:

Используйте короткие, описательные и действенные слова или фразы, чтобы сделать команды понятными пользователю. Например, вместо названия Create a reminder используйте Remind me .
Рассмотрите возможность использования уникального или общего имени для вашей команды. Если ваша команда описывает типичное взаимодействие или функцию, вы можете использовать общее имя, которое пользователи узнают и ожидают, например Settings или Feedback . В противном случае попробуйте использовать уникальные имена команд, поскольку, если имя вашей команды одинаково для других приложений чата, пользователю придется фильтровать похожие команды, чтобы найти и использовать вашу.

Чтобы описать команду:

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

Настройте команду в консоли Google Cloud

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

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

В консоли Google Cloud выберите «Меню» > «API и службы» > «Включенные API и службы» > «API Google Chat».
Перейдите на страницу API Google Chat.
Нажмите Конфигурация .
В разделе «Дополнительные настройки» перейдите в раздел «Триггеры» и убедитесь, что поле команды приложения содержит триггер, например конечную точку HTTP или функцию сценария приложения. Вы должны использовать этот триггер в следующем разделе, чтобы ответить на команду.
В разделе «Команды» нажмите «Добавить команду» .
Введите следующую информацию о команде:
1. Идентификатор команды: число от 1 до 1000, которое ваше приложение Chat использует для распознавания команды и возврата ответа.
2. Тип команды: выберите «Быстрая команда» или «Слэш-команда» .
3. Если вы настраиваете команду с косой чертой, введите значение в поле имени команды с косой чертой, чтобы указать, какие пользователи вводят команду для вызова этой команды. Должно начинаться с косой черты, содержать только текст и может содержать до 50 символов. Например, /remindMe .
4. Имя: понятное имя команды. Имена могут содержать до 50 символов и могут включать специальные символы.
5. Описание: текст, описывающий, как использовать и форматировать команду. Описания могут содержать до 50 символов.
Необязательно: если вы хотите, чтобы приложение Chat отвечало на команду диалоговым окном, установите флажок Открыть диалоговое окно.
Нажмите Сохранить .

Теперь команда настроена для приложения Chat.

Ответить на команду

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

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

В следующем коде показан пример приложения чата, которое отвечает на команду косой черты /about текстовым сообщением. Чтобы реагировать на команды с косой чертой, приложение Chat обрабатывает объекты событий из триггера команды приложения . Если полезные данные объекта события содержат идентификатор команды с косой чертой, приложение 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 Chat .

Чтобы узнать, как протестировать и использовать команду в пользовательском интерфейсе чата, см. раздел «Использование приложений в Google Chat» в справочной документации Google Chat.

Просмотрите примеры приложений Chat , в которых используются команды
Отправить сообщение
Открытие интерактивных диалогов