Using dialogs in apps

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.