Открытие интерактивных диалогов

Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям.

На этой странице описывается, как приложение Google Chat может открывать диалоговые окна для отображения пользовательских интерфейсов (UI) и ответа пользователям.

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

Диалоги представляют собой оконные интерфейсы на основе карточек, которые открываются из чата или сообщения. Диалог и его содержимое видны только пользователю, который его открыл.

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

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

Node.js

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

Примечание. Примеры кода в этом руководстве написаны для запуска как функция Google Cloud для Node.js.

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

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

Открыть диалог

Рис. 1. Приложение чата, открывающее диалоговое окно для сбора контактной информации.

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

1. Запускайте запрос диалога при взаимодействии с пользователем.
2. Обработайте запрос, вернувшись и открыв диалоговое окно.
3. После того как пользователи отправят информацию, обработайте отправку, закрыв диалоговое окно или вернув другое диалоговое окно.

Запустить запрос диалога

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

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

• Ответить на команду косой черты. Чтобы инициировать запрос слэш-команды, необходимо установить флажок «Открывает диалог» при настройке команды .
• Ответьте на нажатие кнопки в сообщении , либо в карточке, либо в нижней части сообщения. Чтобы инициировать запрос от кнопки в сообщении, вы настраиваете действие кнопки onClick , устанавливая для нее interaction OPEN_DIALOG .

Рис. 2. Приложение Chat отправляет сообщение, предлагающее пользователям использовать косую черту /addContact .
Сообщение также включает кнопку, которую пользователи могут нажать для запуска команды.

Следующий JSON показывает, как инициировать запрос диалогового окна с помощью кнопки в сообщении-карточке. Чтобы открыть диалоговое окно, установите для поля onClick.action.interaction кнопки значение OPEN_DIALOG :

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

Где BUTTON_TEXT — это текст, который отображается на кнопке, а ACTION_FUNCTION — это функция, которая запускается для открытия начального диалогового окна.

Открыть начальный диалог

Когда пользователь запускает запрос диалога, ваше приложение Chat получает объект события с полезными данными, которые указывают, что объект dialogEventType имеет значение REQUEST_DIALOG .

Чтобы открыть диалоговое окно, ваше приложение чата может ответить на запрос, вернув объект RenderActions с навигацией pushCard для отображения карточки. Карточка должна содержать любые элементы пользовательского интерфейса (UI), включая один или несколько sections[] виджетов. Для сбора информации от пользователей вы можете указать виджеты ввода формы и виджет кнопки. Дополнительные сведения о разработке входных данных для форм см. в разделе Сбор и обработка информации от пользователей .

Следующий JSON показывает, как приложение Chat возвращает ответ, открывающий диалоговое окно:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

Где BUTTON_TEXT — это текст, который отображается на кнопке (например, Next или Submit »), WIDGETS представляет собой один или несколько виджетов ввода формы , а ACTION_FUNCTION — это функция обратного вызова действия, которая запускается, когда пользователи нажимают кнопку.

Обработка отправки диалога

Когда пользователи нажимают кнопку, которая отправляет диалоговое окно, ваше приложение Chat получает объект события с объектом ButtonClickedPayload . В полезных данных для параметра dialogEventType установлено значение SUBMIT_DIALOG .

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

• Верните другое диалоговое окно, чтобы заполнить другую карточку или форму.
• Закройте диалоговое окно после проверки данных, отправленных пользователем, и, при необходимости, отправьте сообщение с подтверждением.

Необязательно: вернуть другое диалоговое окно.

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

Для обработки данных, вводимых пользователями, приложение Chat обрабатывает данные в объекте commonEventObject.formInputs события. Дополнительные сведения о получении значений из виджетов ввода см. в разделе Сбор и обработка информации от пользователей .

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

В этом примере приложение чата открывает начальное диалоговое окно, которое ведет ко второму диалоговому окну для подтверждения перед отправкой:

Node.js

Этот пример выполняется как функция Google Cloud .

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

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

В этом примере отправляется карточное сообщение, возвращая card JSON . Вы также можете использовать службу карточек Apps Script .

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

Где WIDGETS представляет любые другие виджеты ввода формы .

Закрыть диалог

Когда пользователи нажимают кнопку «Отправить» в диалоговом окне, ваше приложение Chat выполняет связанное с ним действие и предоставляет объекту события buttonClickedPayload , для которого установлено следующее значение:

• isDialogEvent имеет true .
• dialogEventType — SUBMIT_DIALOG .

Приложение Chat должно возвращать объект RenderActions с EndNavigation для которого установлено значение CLOSE_DIALOG .

Необязательно: отображение уведомления

При закрытии диалогового окна вы также можете отобразить текстовое уведомление.

Чтобы отобразить уведомление, верните объект RenderActions с установленным полем notification .

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

Node.js

Этот пример выполняется как функция Google Cloud .

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

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

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Подробности о передаче параметров между диалогами см. в разделе Перенос данных на другую карту .

Необязательно: отправьте сообщение с подтверждением.

Закрывая диалоговое окно, вы также можете отправить новое сообщение или обновить существующее.

Чтобы отправить новое сообщение, верните объект DataActions с полем CreateMessageAction установленным в новом сообщении. Например, чтобы закрыть диалоговое окно и отправить текстовое сообщение, верните следующее:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Чтобы обновить сообщение после того, как пользователь отправит диалоговое окно, верните объект DataActions , который содержит одно из следующих действий:

• UpdateMessageAction : обновляет сообщение, отправленное приложением чата, например сообщение, из которого пользователь запросил диалог.
• UpdateInlinePreviewAction : обновляет карточку из предварительного просмотра ссылки .

Устранение неполадок

Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.

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