This page explains how to build a homepage for your Google Chat app. App home is a customizable card interface that a Chat app sends to a user when they open a direct message with the Chat app.
For example, you can configure the app home card message to include tips for interacting with the Chat app using slash commands. For end users, app home is only available in a Chat app's direct message if the app developer enables the feature.
Use the Card Builder to design and preview JSON card messages for Chat apps:
Open the Card BuilderPrerequisites
Python
A Google Chat app that's enabled for interactive features. To create an interactive Chat app using an HTTP service, complete this quickstart.
Apps Script
A Google Chat app that's enabled for interactive features. To create an interactive Chat app in Apps Script, complete this quickstart.
Configure in the Google Cloud console
Python
In the Google Cloud console, go to Menu > More products > Google Workspace > Product Library > Google Chat API.
Click Manage, and then click the Configuration tab.
Enable Support App Home.
Select the Support App Home checkbox.
In the App Home URL field, add a URL. This value is usually the same URL as the App URL. This URL is called for
APP_HOME
events.Click Save.
Apps Script
In the Google Cloud console, go to Menu > More products > Google Workspace > Product Library > Google Chat API.
Click Manage, and then click the Configuration tab.
Select the Support App Home checkbox.
Click Save.
Configure your Chat app
Configure your Chat app for app home.
Python
When a user open a direct message from a Chat app, an
APP_HOME
event is sent to your Chat app. When an
Chat app receives this event, a JSON instance of
RenderActions
is returned with pushCard
navigation.
@app.route('/', methods=['POST'])
def on_event():
event = request.get_json()
chat = event.get('chat')
if chat is not None:
return handle_chat_event(event)
def handle_chat_event(event):
if event['chat'].get('type') == 'APP_HOME':
return get_app_home_card()
def get_app_home_card():
return {
"action": {
"navigations": [
{
"pushCard": {
"sections": [
{
"widgets": [
{
"buttonList": {
"buttons": [
{
"text": "Open documentation",
"onClick": {
"openLink": {
"url": "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
}
}
]
}
}
Apps Script
This example sends a card message by returning card JSON. You can also use the Apps Script card service.
Implement an onAppHome
function to return a JSON instance of
RenderActions
with pushCard
navigation:
// "onAppHome" is the pre-defined name of the callback that the Chat servers
// execute.
function onAppHome() {
return {
action: {
navigations: [
{
pushCard: getCard()
}
]
}
};
}
function getCard() {
return {
sections: [
{
widgets: [
{
buttonList: {
buttons: [
{
text: "Open documentation",
onClick: {
openLink: {
url: "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
};
}
Update an app home card
The app home card can be updated when a user submits information or closes a
dialog. For example, the initial app home card contains a welcome message that
asks a user to fill out a form with information. After the user completes the
form, the app home card is updated. The update must be returned with an instance
of RenderActions
that contains an updateCard
navigation.
Python
For HTTP apps, updating the app home card is similar to
Process information inputted by users,
but you must return RenderActions
. invokedFunction
represents the name of
the invoked function associated with the Card
widget. For more information,
see
CommonEventObject
.
In the following example,
submitForm
shows that the user has submitted form
data:
@app.route('/', methods=['POST'])
def on_event():
event = request.get_json()
chat = event.get('chat')
if chat is not None:
return handle_chat_event(event)
def handle_chat_event(event):
if event['chat'].get('type') == 'SUBMIT_FORM':
event_object = event.get('commonEventObject')
if event_object is not None:
// Forms
if 'submitForm' == event_object.get('invokedFunction'):
return {
'render_actions': {
'action': {
'navigations': [{
'updateCard': get_update_card()
}]
}
}
}
def get_update_card():
return {
"action": {
"navigations": [{
"pushCard": {
"sections": [{
"widgets": [{
"buttonList": {
"buttons": [{
"text": "Open documentation",
"onClick": {
"openLink": {
"url": "https://developers.google.com/chat"
}
},
}]
}
}]
}]
}
}]
}
}
Apps Script
This example sends a card message by returning card JSON. You can also use the Apps Script card service.
// Called from elsewhere (i.e. on button press).
function updateAppHomeCard(event) {
return {
render_actions: {
action: {
navigations: [
{
updateCard: getCard()
}
]
}
}
}
}
function getCard() {
return {
sections: [
{
widgets: [
{
buttonList: {
buttons: [
{
text: "Open documentation",
onClick: {
openLink: {
url: "https://developers.google.com/chat"
}
}
}
]
}
}
]
}
]
};
}
Limitations
In general,
navigation
is
unavailable for Chat apps. You can't return a stack of cards.
Only pushCard
(for initial response) and updateCard
(for updates) are
available for Chat apps.
Related topics
To open a dialog, use the
OPEN_DIALOG
interaction. For more information, see Open a dialog in response to an app home card.To close a dialog, use the
CLOSE_DIALOG
interaction to close the dialog and return to the app home card or useCLOSE_DIALOG_EXECUTE
interaction to close the dialog and refresh the app home card. For more information, see Respond to a dialog for app home card.For an example of how to use app home, see the issue management Chat app in the codelab Build apps for Google Chat with Gemini.