Send an app home card message for a Google Chat app

This page explains how to create and send an app home card message for your Chat app. App home is a customizable card message 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 apps'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 Builder

Prerequisites

Python

Apps Script

Configure in the Google Cloud console

Python

  1. In the Google Cloud console, go to Menu > More products > Google Workspace > Product Library > Google Chat API.

    Go to Google Chat API

  2. Click Manage, and then click the Configuration tab.

  3. Enable Support App Home.

  4. Select the Support App Home checkbox.

  5. 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.

  6. Click Save.

Apps Script

  1. In the Google Cloud console, go to Menu > More products > Google Workspace > Product Library > Google Chat API.

    Go to Google Chat API

  2. Click Manage, and then click the Configuration tab.

  3. Select the Support App Home checkbox.

  4. Click Save.

Configure your Chat app

Configure your Chat app to send a new card message 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 app receives this event, a JSON instance of RenderActions is returned with push_card navigation.

The following example shows an event:

@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 "Card v2" representing App Home.

The following example shows a card that is configured to include a button link to documentation:

{
  action: {
    navigations: [
      {
        push_card: {
          sections: [
            {
              widgets: [
                {
                  buttonList: {
                    buttons: [
                      {
                        text: "Open documentation",
                        onClick: {
                          openLink: {
                            url: "https://developers.google.com/chat"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

Implement an onAppHome function to return a JSON instance of RenderActions with push_card navigation:

// "onAppHome" is the pre-defined name of the callback that the Chat servers
// execute.
function onAppHome() {
  return {
    action: {
      navigations: [
        {
          push_card: getCard()
        }
      ]
    }
  };
}

function getCard() {
  return {
    sections: [
      {
        widgets: [
          {
            buttonList: {
              buttons: [
                {
                  text: "Open documentation",
                  onClick: {
                    openLink: {
                      url: "https://developers.google.com/chat"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  };
}

Update an app home card message

The app home card message can be updated when a user submits information in a card message or closes a dialog. For example, the initial app home card message is a welcome message that asks a user to fill out a form with information. After the user completes the form, an updated app home card message is sent. The update must be returned with an instance of RenderActions that contains an update_card navigation.

Python

For HTTP apps, updating the app home card message 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': [{
                'update_card': get_update_card
              }]
            }
          }
        }

def get_update_card:
  // Return "Card v2" representing App Home.
  ...

Apps Script

// Called from elsewhere (i.e. on button press).
function updateAppHomeCard(event) {
  return {
    render_actions: {
      action: {
        navigations: [
          {
            update_card: getCard()
          }
        ]
      }
    }
  }
}

function getCard() {
  // Return "Card v2" representing App Home.
  ...
}