You can use dialogs in your apps to interact with users. To do this, you create slash commands that invoke dialogs. In your dialogs, users can enter text in fields, click buttons, and so on. You can even invoke another dialog from a dialog.
Creating slash commands to invoke dialogs
You can specify slash commands to invoke dialogs when you configure your app in the API console. For example:
Name: /showPoll
CommandId: 1
Description: Show poll to user in dialog
Triggers Dialog: yes
Name: /addContact
CommandId: 2
Description: Shows a dialog to add a contact
Triggers Dialog: yes
Handling an event for a dialog
When the user types a slash command to trigger a dialog, your app receives an
onMessage
event as usual, but with additional information:
...
message: {
slashCommand: { commandId: 1 },
...
dialogEventType: 'REQUEST_DIALOG',
type: 'MESSAGE',
isDialogEvent: true
}
You can handle the event by switching based on the slash command as a
REQUEST_DIALOG
event:
function onMessage(event) {
// Determine whether the user invoked a slash command
if (event.message.slashCommand) {
// Respond to the slash command based on its ID
switch (event.message.slashCommand.commandId) {
case 1: // /showPoll
generatePollDialog(message);
case 2: // /addContact
generateDialogForAddContact(message);
}
}
}
Dialogs support all forms of Connection Settings except Cloud Pub/Sub and Dialogflow.
Form submissions
When the user completes a dialog, the result is sent to your app as a form
submission. Your app receives a CARD_CLICKED
event with dialogEventType
set
to SUBMIT_DIALOG
.
{
dialogEventType: 'SUBMIT_DIALOG',
type: 'CARD_CLICKED',
action: {
actionMethodName: 'assign'
},
...
common: {
hostApp: 'CHAT',
formInputs: {
'whotochoose-dropdown': [Object],
whotochoose: [Object],
email: [Object]
},
invokedFunction: 'assign'
},
isDialogEvent: true
}
The formInputs
field contains the values the user chose in the dialog. You can
process these just as you would any other inputs. The actionMethodName
is
derived from the onclick.action.function
value so the app can determine which
dialog element the user interacted with to handle the request.
Your app can respond to a dialog form submission in either of 2 ways:
- OK (just acknowledge)
- Follow-up dialog
OK response
Your app can respond with a simple acknowledgment:
{
"action_response": {
"type": "DIALOG",
"dialog_action": {
"action_status": "OK"
}
}
}
This response indicates the dialog was submitted successfully. A value of
action_status
other than OK
indicates an error result. In that case,
action_status
is set to indicate the error that occurred. If you respond with
status 200, the dialog will be closed.
Respond to a dialog with a follow-up dialog
Your app can respond to a dialog by creating another dialog. In this case, it
should respond as if to a REQUEST_DIALOG
event. In this way, you can chain
multiple dialogs together, with each dialog chosen based on the results of the
previous one.
Dialogs use the card.v1.Card
add-on. You can respond with
a dialog by specifying a dialog card within your ActionResponse.
For example, you could respond with a dialog like this:
{
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"header": {
"title": "Here is a dialog!",
"subtitle": "Cool!"
},
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsible_widgets_count": 1,
"widgets": [
{
"decorated_text": {
"top_label": "Top label 1",
"text": "Some content here",
"wrap_text": false,
"icon": {
"known_icon": "PERSON"
}
}
}
]
}
]
}
}
}
}
}
Respond to a dialog with a text message or a card
To respond to a dialog with a simple text message or card as a follow-up response to a dialog, send an asychronous reply by calling spaces.messages.create
using the Google Chat REST API with a service account.
Current limitations
The following features of cards are not supported in app dialogs:
- Date picker
- App Card
- Server-generated autocomplete suggestions
- (Suggestions returned with the dialog response are supported)
on_change_action
More information
For more information on creating apps, see the Chat REST API Reference.