Собирайте и обрабатывайте информацию от пользователей Google Chat.

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

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

Приложения чата запрашивают у пользователей информацию для выполнения действий в чате или за его пределами, в том числе следующими способами:

• Настроить параметры. Например, чтобы позволить пользователям настраивать параметры уведомлений или настраивать и добавлять приложение Chat в одно или несколько пространств.
• Создавайте или обновляйте информацию в других приложениях Google Workspace. Например, позвольте пользователям создавать события в Google Calendar.
• Позвольте пользователям получать доступ и обновлять ресурсы в других приложениях или веб-сервисах. Например, приложение Chat может помочь пользователям обновлять статус тикета поддержки непосредственно из пространства Chat.

Предпосылки

Создавайте формы с использованием карточек

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

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

Чат-приложения могут создавать карточки с использованием следующих виджетов:

• Виджеты ввода формы, которые запрашивают информацию у пользователей. При желании вы можете добавить проверку для виджетов ввода формы, чтобы гарантировать, что пользователи вводят и форматируют информацию правильно. Чат-приложения могут использовать следующие виджеты ввода формы:

  • Текстовые поля ( textInput ) для ввода текста в свободной форме или предлагаемого текста.

  • Входы выбора ( selectionInput ) — это выбираемые элементы пользовательского интерфейса, такие как флажки, радиокнопки и раскрывающиеся меню. Виджеты входов выбора также могут заполнять и предлагать элементы из данных Google Workspace (например, из пространства чата) или динамического источника данных. Подробности см. в следующем разделе Добавление меню множественного выбора .

  • Выбор даты и времени ( dateTimePicker ) для ввода даты и времени.

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

В следующем примере карточка собирает контактную информацию с помощью текстового ввода, выбора даты и времени и выбора:

Дополнительные примеры интерактивных виджетов, которые можно использовать для сбора информации, см. в разделе «Разработка интерактивной карточки или диалога» в документации Google Chat API.

Добавить меню множественного выбора

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

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

• Данные Google Workspace , которые включают пользователей или чат-пространства, членом которых является пользователь. Меню заполняет только элементы из той же организации Google Workspace.
• Внешние источники данных , такие как реляционная база данных. Например, вы можете использовать меню с множественным выбором, чтобы помочь пользователю выбрать из списка лидов продаж из системы управления взаимоотношениями с клиентами (CRM).

Заполнение элементов из источника данных Google Workspace

Чтобы использовать источники данных Google Workspace, укажите поле platformDataSource в виджете SelectionInput . В отличие от других типов ввода выбора, вы пропускаете объекты SelectionItem , поскольку эти элементы выбора динамически извлекаются из Google Workspace.

Следующий код показывает меню множественного выбора пользователей Google Workspace. Для заполнения пользователей вход выбора устанавливает commonDataSource в USER :

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Следующий код показывает меню множественного выбора пространств чата. Для заполнения пространств входной параметр выбора указывает поле hostAppDataSource . Меню множественного выбора также устанавливает defaultToCurrentSpace в true , что делает текущее пространство выбором по умолчанию в меню:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Заполнение элементов из внешнего источника данных

Меню Multiselect также могут заполнять элементы из стороннего или внешнего источника данных. Чтобы использовать внешний источник данных, вы указываете поле externalDataSource в виджете SelectionInput , содержащем функцию, которая запрашивает и возвращает элементы из источника данных.

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

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

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Замените FUNCTION на HTTP URL или имя функции Apps Script, которая запрашивает внешнюю базу данных. Полный пример, показывающий, как возвращать предлагаемые элементы, см. в разделе Suggest multiselect items .

Получайте данные из интерактивных виджетов

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

Вы можете получить значения из объекта commonEventObject.formInputs. WIDGET_NAME , где WIDGET_NAME — это поле name , которое вы указали для виджета. Значения возвращаются как определенный тип данных для виджета.

Ниже показана часть объекта события, где пользователь ввел значения для каждого виджета:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

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

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

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

Предложить множественный выбор элементов

Если карточка содержит меню с множественным выбором, которое заполняет элементы из внешнего источника данных , приложение Chat может возвращать предлагаемые элементы на основе того, что пользователи вводят в меню. Например, если пользователь начинает вводить Atl для меню, которое заполняет города в Соединенных Штатах, ваше приложение Chat может автоматически предложить Atlanta до того, как пользователь закончит вводить. Приложение Chat может предложить до 100 элементов.

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

1. Обрабатывайте объект события , который приложение чата получает, когда пользователи вводят данные в меню.
2. Из объекта события получите значение, которое вводит пользователь, представленное в поле event.commonEventObject.parameters["autocomplete_widget_query"] .
3. Запросите источник данных, используя введенное пользователем значение, чтобы получить один или несколько SelectionItems для предложения пользователю.
4. Верните предложенные элементы, вернув действие RenderActions с объектом modifyCard .

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

/**
 * 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.selectionInput = function selectionInput(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
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Перенос данных на другую карту

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

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

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

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Где WIDGET_NAME — это name виджета, а USER_INPUT_VALUE — это то, что вводит пользователь. Например, для текстового ввода, который собирает имя человека, имя виджета — contactName , а пример значения — Kai O

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

Ответить на отправленную форму

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

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

/**
 * 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;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle message payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Чтобы обработать и закрыть диалог, вы возвращаете объект RenderActions , который указывает, хотите ли вы отправить сообщение с подтверждением, обновить исходное сообщение или карту или просто закрыть диалог. Для шагов см. Закрыть диалог .

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

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

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