Criar a página inicial de um app do Google Chat

Esta página explica como criar uma página inicial para seu app Google Chat. A página inicial do app é uma interface de cartão personalizável que um app de chat envia para um usuário quando ele abre uma mensagem no app do Chat.

Card da página inicial do app com dois widgets.

Por exemplo, é possível configure a mensagem do card da página inicial do app para incluir dicas de interação com o App do Chat usando comandos de barra. Para usuários finais, a página inicial do app é disponível na mensagem direta de um app do Chat apenas se o desenvolvedor de apps ativa o recurso.


Use o Card Builder para criar e visualizar mensagens de cards JSON para apps do Chat:

Abrir o Card Builder

Pré-requisitos

Python

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.

Apps Script

Um app do Google Chat com recursos interativos ativados. Para criar um interativo com o app Chat no Apps Script, conclua este guia de início rápido.

Node.js

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.

Java

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.

Configurar a API Chat

Para oferecer suporte à página inicial, atualize a configuração da API Chat no console do Google Cloud.

Python

  1. No console do Google Cloud, acesse Menu > Mais produtos > Google Workspace > Biblioteca de produtos > API Google Chat.

    Acessar a API Google Chat

  2. Clique em Gerenciar e depois na guia Configuração.

  3. Marque a caixa de seleção Support App Home.

  4. No campo URL da página inicial do app, adicione um URL. Geralmente, esse valor é o mesmo como o URL do app. Esse URL é chamado para Eventos APP_HOME.

  5. Clique em Salvar.

Apps Script

  1. No console do Google Cloud, acesse Menu > Mais produtos > Google Workspace > Biblioteca de produtos > API Google Chat.

    Acessar a API Google Chat

  2. Clique em Gerenciar e depois na guia Configuração.

  3. Marque a caixa de seleção Support App Home.

  4. Clique em Salvar.

Node.js

  1. No console do Google Cloud, acesse Menu > Mais produtos > Google Workspace > Biblioteca de produtos > API Google Chat.

    Acessar a API Google Chat

  2. Clique em Gerenciar e depois na guia Configuração.

  3. Marque a caixa de seleção Support App Home.

  4. No campo URL da página inicial do app, adicione um URL. Geralmente, esse valor é o mesmo como o URL do app. Esse URL é chamado para Eventos APP_HOME.

  5. Clique em Salvar.

Java

  1. No console do Google Cloud, acesse Menu > Mais produtos > Google Workspace > Biblioteca de produtos > API Google Chat.

    Acessar a API Google Chat

  2. Clique em Gerenciar e depois na guia Configuração.

  3. Marque a caixa de seleção Support App Home.

  4. No campo URL da página inicial do app, adicione um URL. Geralmente, esse valor é o mesmo como o URL do app. Esse URL é chamado para Eventos APP_HOME.

  5. Clique em Salvar.

Criar página inicial do app

O card da página inicial do app é iniciado quando um usuário abre uma mensagem direta no do Chat, que pode ser atualizado como resposta de um evento interativo, como um clique em um botão, o envio de um formulário ou o fechamento de uma caixa de diálogo.

No exemplo a seguir, o app do Chat exibe Um card inicial da página inicial do app que mostra a hora em que o cartão foi criado e um botão. Quando um usuário clica no botão, o app do Chat retorna um cartão atualizado que exibe a hora em que o cartão atualizado foi criado.

Criar o cartão inicial para a página inicial do app

Para criar a página inicial, o app do Chat precisa processar APP_HOME eventos de interação e retornam uma instância de RenderActions com navegação pushCard.

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

Implemente a função onAppHome que é chamada após todos os eventos APP_HOME:

Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.

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;
}

Atualizar um card na página inicial do app

Se o card inicial da página inicial tiver widgets interativos, como botões ou entradas de seleção, o app do Chat precisa processar os eventos de interação relacionados retornando uma instância do RenderActions com a navegação updateCard. Para saber mais sobre como lidar com widgets, consulte Processar as informações inseridas pelos usuários.

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

Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.

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;
}

Limitações

Em geral, navigation é indisponível para apps do Chat. Não é possível devolver uma pilha de cards. Apenas pushCard (para resposta inicial) e updateCard (para atualizações) são disponível para os apps do Chat.