Collect and process information from Google Chat users

This guide describes how Google Chat apps can collect and process information from users by building form inputs in card-based interfaces.

Chat apps request information from users to perform actions in or outside of Chat, including in the following ways:

• Configure settings. For example, to let users customize notification settings or configure and add the Chat app to one or more spaces.
• Create or update information in other Google Workspace applications. For example, let users create a Google Calendar event.
• Let users access and update resources in other apps or web services. For example, Chat app can help users update the status of a support ticket directly from a Chat space.

Prerequisites

• HTTP service with Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

Build forms using cards

To collect information, Chat apps design forms and their inputs, and build them into cards. To display cards to users, Chat apps can use the following Chat interfaces:

• Messages that contain one or more cards.
• Homepages, which is a card that appears from the Home tab in direct messages with the Chat app.
• Dialogs, which are cards that open in a new window from messages and homepages.

Chat apps can build the cards using the following widgets:

• Form input widgets that request information from users. Optionally, you can add validation to form input widgets, to ensure that users input and format information correctly. Chat apps can use the following form input widgets:

  • Text inputs (textInput) for free-form or suggested text.
  • Selection inputs (selectionInput) are selectable UI elements such as checkboxes, radio buttons, and drop-down menus. Selection input widgets can also populate items from static or dynamic data sources. For example, users can select from a list of Chat spaces that they're a member of.
  • Date time pickers (dateTimePicker) for date and time entries.

• A button widget so that users can submit values that they've input in the card. After a user clicks the button, the Chat app can then process the information that it receives.

The following displays a card consisting of three different types of date and time inputs:

For more examples of interactive widgets that you can use to collect information, see Design an interactive card or dialog.

Receive data from interactive widgets

Whenever users click a button, Chat apps receive a CARD_CLICKED interaction event that contains information about the interaction. The payload of CARD_CLICKED interaction events contains a common.formInputs object with any values that the user inputs.

You can retrieve the values from the object common.formInputs.WIDGET_NAME, where WIDGET_NAME is the name field that you specified for the widget. The values are returned as a specific data type for the widget (represented as an Inputs object). In the following example, a card collects contact information using a text input, date time picker, and selection input widget:

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

Handle the interaction event

When a user inputs data in a card or dialog, your Chat app receives a Chat app CARD_CLICKED interaction event that contains the values input by the user.

The following shows a portion of a CARD_CLICKED interaction event where a user inputted values for each widget:

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

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

To receive the data, your Chat app handles the interaction event to get the values that users input into widgets. The following table shows how to get the value for a given form input widget. For each widget, the table shows the data type that the widget accepts, where the value is stored in the interaction event, and an example value.

Transfer data to another card

After a user submits information from a card, you might need to return additional cards to do any of the following:

• Help users to complete longer forms by creating distinct sections.
• Let users preview and confirm information from the initial card, so that they can review their answers before submitting.
• Dynamically populate the remaining parts of the form. For example, to prompt users to create an appointment, a Chat app could display an initial card that requests the reason for the appointment, and then populates another card that provides available times based on the appointment type.

To transfer the data input from the initial card, you can build the button widget with actionParameters that contain the widget's name and the value the user inputs, as shown in the following example:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Where WIDGET_NAME is the name of the widget and the USER_INPUT_VALUE is what the user inputs. For example, for a text input that collects a person's name, the widget name is contactName and an example value is Kai O.

When a user clicks the button, your Chat app receives a CARD_CLICKED interaction event. To retrieve the values, you can use the event.common.parameters object.

The following shows an example of how you can pass parameters containing user input data to a function that opens the next card:

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Respond to a form submission

After receiving the data from a card message or dialog, the Chat app responds by either acknowledging receipt or returning an error.

In the following example, a Chat app sends a text message to confirm that it has successfully received a form submitted from a card message.

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

To process and close a dialog, you return an ActionResponse object that specifies whether you want to send a confirmation message, update the original message or card, or just close the dialog. For steps, see Close a dialog.

Troubleshoot

When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, see Troubleshoot and fix Google Chat errors.

Related topics

• View Chat app samples that process information from users.
• Open interactive dialogs