Build a homepage for a Google Chat app

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.

App home card with two widgets.

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 Builder

Prerequisites

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.

Node.js

A Google Chat app that's enabled for interactive features. To create an interactive Chat app using an HTTP service, complete this quickstart.

Java

A Google Chat app that's enabled for interactive features. To create an interactive Chat app using an HTTP service, complete this quickstart.

Configure the Chat API

To support app home, you must update your Chat API configuration 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. Select the Support App Home checkbox.

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

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

Node.js

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

  5. Click Save.

Java

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

  5. Click Save.

Build app home

The app home card is initiated when a user opens a direct message from the Chat app and it can be updated as a response of an interactive event such as a button click, form submission, or dialog closure.

In the following example, the Chat app displays an initial app home card that displays the time the card was created and a button. When a user clicks the button, the Chat app returns an updated card that displays the time the updated card was created.

Create the initial card for app home

To build app home, the Chat app must handle APP_HOME interaction events and return an instance of RenderActions with pushCard navigation.

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Apps Script

Implement the onAppHome function that is called after all APP_HOME events:

This example sends a card message by returning card JSON. You can also use the Apps Script card service.

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Update an app home card

If your initial app home card contains interactive widgets, such as buttons or selection inputs, your Chat app must handle the related interaction events by returning an instance of RenderActions with updateCard navigation. To learn more about handling interactive widgets, see Process information inputted by users.

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Apps Script

This example sends a card message by returning card JSON. You can also use the Apps Script card service.

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

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.