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

Nesta página, explicamos 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 de interação com o app Chat ou 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 de usuário para apps do Chat:

Abra o Card Builder

Pré-requisitos

Node.js

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat usando um serviço HTTP, conclua este guia de início rápido.

Python

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat usando um serviço HTTP, conclua este guia de início rápido.

Java

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat usando um serviço HTTP, conclua este guia de início rápido.

Apps Script

Um app do Google Chat que recebe e responde a eventos de interação. 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 do Chat

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

Para atualizar as configurações de configuração 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, em seguida, na guia Configuração.

  3. Em Recursos interativos, acesse a seção Funcionalidade e selecione 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. Você pode usar o mesmo URL especificado no campo URL do endpoint HTTP.

  5. Clique em Salvar.

Criar um card da página inicial do app

Quando um usuário abre a página 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 Google Chat pode processar e responder com outros cards ou uma caixa de diálogo.

No exemplo a seguir, o app do Chat mostra um card inicial da página inicial do app com a hora em que ele foi criado e um botão. Quando um usuário clica no botão, o app Chat retorna um card atualizado que mostra a hora em que ele 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 depois de todos os eventos de interação APP_HOME:

Este exemplo envia uma mensagem de card retornando um JSON de card. 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 na página inicial do app

Se o card inicial da página inicial do app 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 navegação updateCard. Para saber mais sobre como processar 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 CARD_CLICKED evento de interação 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 card retornando um JSON de card. 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 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 pede para o usuário adicionar 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 navegação updateCard que contém um objeto Card. No exemplo a seguir, um app do Chat responde ao clique em um botão de um card da página inicial do 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 volta ao card inicial da página inicial do app Chat.
  • CLOSE_DIALOG_AND_EXECUTE: fecha a caixa de diálogo e atualiza o card da página inicial do app.

O exemplo de código a seguir usa CLOSE_DIALOG para fechar uma caixa de diálogo e voltar ao card da página inicial do app:

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

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