Support interactive dialogs (original) (raw)

This page describes how your Chat app can open dialogs to respond to users.

Dialogs are windowed, card-based interfaces that open from a Chat space or message. The dialog and its contents are only visible to the user that opened it.

Chat apps can use dialogs to request and collect information from Chat users, including multi-step forms. For more details on building form inputs, see Collect and process information from users.

Prerequisites

Node.js

A Google Chat app that receives and responds to interaction events. To create an interactive Chat app using an HTTP service, complete this quickstart.

Python

A Google Chat app that receives and responds to interaction events. To create an interactive Chat app using an HTTP service, complete this quickstart.

Java

A Google Chat app that receives and responds to interaction events. To create an interactive Chat app using an HTTP service, complete this quickstart.

Apps Script

A Google Chat app that receives and responds to interaction events. To create an interactive Chat app in Apps Script, complete this quickstart.

Open a dialog

A dialog featuring a variety of different widgets.

Figure 1: Asample Chat app that opens a dialog to collect contact information.

This section explains how to respond and set up a dialog by doing the following:

  1. Trigger the dialog request from a user interaction.
  2. Handle the request by returning and opening a dialog.
  3. After users submit information, process the submission by either closing the dialog or returning another dialog.

Trigger a dialog request

A Chat app can only open dialogs to respond to a user interaction, such as a command or a button click from a message in a card.

To respond to users with a dialog, a Chat app must build an interaction that triggers the dialog request, such as the following:

Button that triggers a dialog

Figure 2: A Chat app sends a message that prompts users to use the /addContact slash command.
The message also includes a button that users can click to trigger the command.

The following code sample shows how to trigger a dialog request from a button in a card message. To open the dialog, thebutton.interactionfield is set to OPEN_DIALOG:

Open the initial dialog

When a user triggers a dialog request, your Chat app receives an interaction event, represented as anevent type in the Chat API. If the interaction triggers a dialog request, the event'sdialogEventType field is set to REQUEST_DIALOG.

To open a dialog, your Chat app can respond to the request by returning anactionResponseobject with the type set to DIALOG andMessageobject. To specify the contents of the dialog, you include the following objects:

The following code sample shows how a Chat app returns a response that opens a dialog:

Handle the dialog submission

When users click a button that submits a dialog, your Chat app receives a CARD_CLICKED interaction event where the dialogEventTypeis SUBMIT_DIALOG. To understand how to collect and process the information in the dialog, seeCollect and process information from Chat users.

Your Chat app must respond to the interaction event by doing one of the following:

Optional: Return another dialog

After users submit the initial dialog, Chat apps can return one or more additional dialogs to help users review information before submitting, complete multi-step forms, or populate form content dynamically.

To process the data that users input, the Chat app uses theevent.common.formInputsobject. To learn more about retrieving values from input widgets, seeCollect and process information from users.

To keep track of any data that users input from the initial dialog, you must add parameters to the button that opens the next dialog. For details, seeTransfer data to another card.

In this example, a Chat app opens an initial dialog that leads to a second dialog for confirmation before submitting:

Close the dialog

When users click a button on a dialog, your Chat app executes its associated action and provides the event object with the following information:

The Chat app should return anActionResponseobject with its type set to DIALOG, and dialogAction populated. If the action did not fail then the dialogAction.actionStatus should be OK like in the following example:

Optional: Display a temporary notification

When you close the dialog, you can also display a temporary text notification to the user that is interacting with the app.

The Chat app can respond with a success or error notification by returning anActionResponsewith actionStatus set.

The following example checks that parameters are valid and closes the dialog with text notification when invalid:

For details about passing parameters between dialogs, seeTransfer data to another card.

Optional: Send a confirmation Chat message

When you close the dialog, you can also send a new Chat message, or update an existing one.

To send a new message, return anActionResponseobject with the type set to NEW_MESSAGE. The following example closes the dialog with confirmation text message:

To update a message, return an actionResponse object that contains the updated message and sets the type to one of the following:

Troubleshoot

When a Google Chat app orcard 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, seeTroubleshoot and fix Google Chat errors.