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

Esta página explica como criar uma página inicial para mensagens diretas com seu app do Google Chat. Uma página inicial, chamada de página inicial do app na API Google Chat, é uma interface de card personalizável que aparece na guia Início dos espaços de mensagens diretas entre um usuário e um app do Chat.

Card inicial do app com dois widgets.
Figura 1: exemplo de uma página inicial que aparece em mensagens diretas com um app de chat.

Você pode usar a página inicial do app para compartilhar dicas sobre como interagir com o app do Chat ou para permitir que os usuários acessem e usem um serviço ou ferramenta externa no Chat.

Use o Card Builder para criar e visualizar mensagens e interfaces do usuário para apps do Chat:

Abrir o criador de cards

Pré-requisitos

Node.js

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

Python

Um app do Google Chat com recursos interativos ativados. Para criar um app do Chat interativo usando 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 app de chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Apps Script

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

Configurar a página inicial do app de chat

Para oferecer suporte à página inicial, configure o app do Chat para receber APP_HOME eventos de interação. O app do Chat recebe esse evento sempre que um usuário clica na guia Início de uma mensagem direta com o app do Chat.

Para atualizar suas configurações no console do Google Cloud, faça o seguinte:

  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 na guia Configuração.

  3. Em Recursos interativos, acesse a seção Funcionalidade para configurar a página inicial do app:

    1. Marque a caixa de seleção Receber mensagens individuais.
    2. Marque a caixa de seleção Suporte à página inicial do app.

  4. Se o app de chat usar um serviço HTTP, acesse Configurações de conexão e especifique um endpoint para o campo URL da página inicial do app. Use o mesmo URL especificado no campo URL do endpoint HTTP.

  5. Clique em Salvar.

Criar um card para a página inicial do app

Quando um usuário abrir a tela inicial do app, o app Chat precisa processar o evento de interação APP_HOME retornando uma instância de RenderActions com navegação pushCard e um Card. Para criar uma experiência interativa, o card pode conter widgets interativos, como botões ou entradas de texto, que o app do Chat pode processar e responder com outros cards ou uma caixa de diálogo.

No exemplo abaixo, o app Chat mostra um card inicial na tela inicial do app que mostra a hora em que o card foi criado e um botão. Quando um usuário clica no botão, o app do Chat retorna um card atualizado com o horário em que o card atualizado foi criado.

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

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"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Process Google Chat events
@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() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

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

Este exemplo envia uma mensagem de cartão retornando o card JSON. 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"
      }}
    }]}}
  ]}]};
}

Responder a interações da 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 precisará processar os eventos de interação relacionados retornando uma instância de RenderActions com a navegação updateCard. Para saber mais sobre o processamento de widgets interativos, consulte Processar informações inseridas pelos usuários.

No exemplo anterior, o card inicial da página inicial do app incluía um botão. Sempre que um usuário clica no botão, um evento de interação CARD_CLICKED aciona a função updateAppHome para atualizar o card da página inicial do app, conforme mostrado neste código:

Node.js

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

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()
  }]}}}

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

Apps Script

Este exemplo envia uma mensagem de cartão retornando o card JSON. 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()
  }]}}};
}

Abrir caixas de diálogo

O app do Chat também pode responder a interações na página inicial do app abrindo caixas de diálogo.

Uma caixa de diálogo com vários widgets diferentes.
Figura 3: uma caixa de diálogo que solicita que o usuário adicione um contato.

Para abrir uma caixa de diálogo na página inicial do app, processe o evento de interação relacionado retornando renderActions com a navegação updateCard que contém um objeto Card. No exemplo abaixo, um app de chat responde a um clique de botão de um card de início de app processando o evento de interação CARD_CLICKED e abrindo uma caixa de diálogo:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Para fechar uma caixa de diálogo, processe os seguintes eventos de interação:

  • CLOSE_DIALOG: fecha a caixa de diálogo e retorna ao card inicial da tela inicial do app de chat.
  • CLOSE_DIALOG_AND_EXECUTE: fecha a caixa de diálogo e atualiza o card de início do app.

O exemplo de código abaixo usa CLOSE_DIALOG para fechar uma caixa de diálogo e retornar ao card de início do app:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

Para coletar informações dos usuários, você também pode criar caixas de diálogo sequenciais. Para aprender a criar caixas de diálogo sequenciais, consulte Abrir e responder a caixas de diálogo.