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 sua app Google Chat. Uma página inicial, conhecida como página inicial do app no A API Google Chat é uma interface de card personalizável que aparece na guia Página inicial. de espaços para mensagens diretas entre um usuário e um app do Chat.

Card da página inicial do app com dois widgets.
Figura 1: exemplo de uma página inicial que aparece em mensagens diretas com um app do 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 Card Builder

Pré-requisitos

Node.js

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

Python

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app de 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 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.

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, Seu app do Chat recebe esse evento sempre que um usuário clicar na guia Início de uma mensagem direta com o App Chat.

Para atualizar as 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 do Chat usar um serviço HTTP, acesse Configurações de conexão e especifique um endpoint para a campo URL da página inicial do app. Você pode usar o mesmo URL especificado no Campo URL do endpoint HTTP.

  5. Clique em Salvar.

Criar um card de início de app

Quando um usuário abre 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 um 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 cartões adicionais 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 cartão atualizado que exibe a hora em que o cartão 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
 *
 * @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;
}

Apps Script

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

Este exemplo envia uma mensagem de card retornando JSON do cartão. Também é possível usar o serviço de cards 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 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.

No exemplo anterior, o card 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 no código a seguir:

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

Seu 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 a seguir, um app do Chat responde a um clique em um botão na página inicial do app processando o CARD_CLICKED evento de interação 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 do app do Chat na página inicial.
  • CLOSE_DIALOG_AND_EXECUTE: fecha a caixa de diálogo e atualiza a página inicial do app. carda.

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.