While apps are powerful on their own, they often work in concert with other systems and require companion applications to connect accounts, authorize data access, display additional data, or configure user preferences.
Request app configuration
In addition to presenting URLs as part of a normal reply, apps can privately present a configuration URL to the user in response to a message.
Return a configuration URL
If completing a request requires additional configuration that can't be completed directly in the app, return a response of the following form:
{
"actionResponse": {
"type": "REQUEST_CONFIG",
"url": "<your-config-URL>"
}
}
This tells Google Chat to present the user with a private prompt, with a link to visit the provided config URL for authentication, authorization, or configuration. A request-config response is mutually exclusive with a regular response message. Any text, cards, or other attributes are ignored.
Every event to your app also includes a configCompleteRedirectUrl parameter.
This URL should be encoded in your configuration URL to be used on completion
of the process. Redirecting to this URL signals to Google Chat that the
configuration request was fulfilled.
When your app starts the flow can depend on the specific message received.
In response to a message like @app help, an app should respond with
a message without requiring additional configuration.
When a user is successfully redirected to the configCompleteRedirectUrl
provided in the original message, Google Chat performs the following steps:
- Erase the prompt that was displayed to the initiating user
- Convert the original message to public, making it visible to other members of the space
- Dispatch the original message to the same app a second time
Visiting a configCompleteRedirectUrl only affects a single user message.
If a user has tried to message an app multiple times and as a result received
multiple prompts, clicking through a particular prompt and completing the
auth / config process only affects that particular message / prompt.
Other messages and prompts remain unchanged.
When an event is re-dispatched in this way, it normally should be identical to the original event; however, there are some situations where the events may differ. For example, when a message mentions both app A and app B, the user will be able to edit the message text if app A responds with a regular message before authenticating with app B. In this case, app B will receive the edited message text after the user completes authentication.
Identify the user in app messages
Each message sent to your app includes the identity of the user interacting with the app.
The example JSON fragment below shows the expected format of the user identity in a message to your app.
{
...,
"user": {
"name": "users/12345678901234567890",
"displayName": "Sasha",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "sasha@example.com"
}
}
Use the value of the users.name property as the primary ID for the user. The
value is a stable and unique ID for each user.
Identify the Chat user outside of Google Chat
In some cases, such as requesting OAuth authorization for an API, your app needs to link to a URL outside of Google Chat while maintaining the user identity. The best way to identify the user in these cases is to guard the destination app with Google Sign-in.
Use the identity token issued
during sign-in to get the user ID. The sub claim contains the user's unique
ID and can be correlated with the ID from Google Chat.
While the two IDs are not exactly identical, they are easily coerced. To
coerce the value of the sub claim to a Google Chat user name, prepend
the value with "users/". For example, the claim value of 123 is equivalent
to the user name users/123 in messages to your Chat app.
Full Example
The MyProfile
app
demonstrates how to use the REQUEST_CONFIG response to initiate app configuration
and uses the identity token from the Google Sign-in response to identify the user.