Criar um app HTTP do Google Chat

Esta página explica como criar um app HTTP do Chat. Há diferentes maneiras de implementar essa arquitetura. No Google Cloud, você pode usar o Cloud Run e o App Engine. Neste guia de início rápido, você vai escrever e implantar uma função do Cloud Run que o app do Chat usa para responder à mensagem de um usuário.

Com essa arquitetura, você configura o Chat para integrar com o Google Cloud ou um servidor local usando HTTP, conforme mostrado no diagrama a seguir:

Arquitetura de um app do Chat usando um serviço da Web em um servidor local.

No diagrama anterior, um usuário que interage com um app HTTP do Chat tem o seguinte fluxo de informações:

  1. Um usuário envia uma mensagem no Chat para um app do Chat, em uma mensagem direta ou em um espaço do Chat.
  2. Uma solicitação HTTP é enviada a um servidor da Web, que é um sistema de nuvem ou local que contém a lógica do app do Chat.
  3. Opcionalmente, a lógica do app do Chat pode ser integrada aos serviços do Google Workspace (como Agenda e Planilhas), outros Serviços do Google (como Maps, YouTube e Vertex AI) ou outros serviços da Web (como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de tickets).
  4. O servidor da Web envia uma resposta HTTP de volta ao serviço do app do Chat no Chat.
  5. A resposta é entregue ao usuário.
  6. Opcionalmente, o app do Chat pode chamar a API Chat para postar mensagens de forma assíncrona ou realizar outras operações.

Essa arquitetura oferece a flexibilidade de usar bibliotecas e componentes que já existem no seu sistema, porque esses apps do Chat podem ser projetados usando diferentes linguagens de programação.

Objetivos

  • Prepare o ambiente.
  • Crie e implante uma função do Cloud Run.
  • Publique o app no Chat.
  • Teste o app.

Pré-requisitos

Configure o ambiente

Antes de usar as APIs do Google, você precisa ativá-las em um projeto na nuvem do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

  • No Console de APIs do Google, ative a API Google Chat, a API Cloud Build, a API Cloud Functions, a API Cloud Pub/Sub, a API Cloud Logging, a API Artifact Registry e a API Cloud Run.

    Ativar as APIs

Crie e implante uma função do Cloud Run

Crie e implante uma função do Cloud Run que gera um card do Chat com o nome de exibição e a imagem do avatar do remetente. Quando o app do Chat recebe uma mensagem, ele executa a função e responde com o card.

Para criar e implantar a função do app do Chat, siga estas etapas:

Node.js

  1. No Console de APIs do Google, acesse a página do Cloud Run:

    Acessar o Cloud Run

    Verifique se o projeto do app do Chat está selecionado.

  2. Clique em Escrever uma função.

  3. Na página Criar serviço, configure a função:

    1. No campo Nome do serviço, insira quickstartchatapp.
    2. Na lista Região, selecione uma região.
    3. Na lista Ambiente de execução, selecione a versão mais recente do Node.js.
    4. Na seção Autenticação, selecione Exigir autenticação.
    5. Clique em Criar e aguarde o Cloud Run criar o serviço. O console vai redirecionar você para a guia Origem.

  4. Na guia Origem:

    1. Em Ponto de entrada, exclua o texto padrão e insira avatarApp.

    2. Substitua o conteúdo de index.js pelo seguinte código:

      node/avatar-app/index.js
      const functions = require('@google-cloud/functions-framework');

// Command IDs (configure these in Google Chat API)
const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
const HELP_COMMAND_ID = 2; // ID for the "Help" quick command

/**
 * Google Cloud Function that handles HTTP requests from Google Chat.
 *
 * @param {Object} req - The HTTP request object sent from Google Chat.
 * @param {Object} res - The HTTP response object.
 */
functions.http('avatarApp', (req, res) => {
  const event = req.body;

  if (event.appCommandMetadata) {
    handleAppCommands(event, res);
  } else {
    handleRegularMessage(event, res);
  }
});

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

/**
 * Handles regular messages (not commands).
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleRegularMessage(event, res) {
  const messageData = createMessage(event.user);
  res.send(messageData);
}

/**
 * Creates a card message with the user's avatar.
 *
 * @param {Object} user - The user who sent the message.
 * @param {string} user.displayName - The user's display name.
 * @param {string} user.avatarUrl - The URL of the user's avatar.
 * @return {Object} - The card message object.
 */
function createMessage({displayName, avatarUrl}) {
  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: {
          title: `Hello ${displayName}!`,
        },
        sections: [{
          widgets: [
            {textParagraph: {text: 'Your avatar picture:'}},
            {image: {imageUrl: avatarUrl}},
          ],
        }],
      },
    }],
  };
}

    3. Clique em Salvar e implantar novamente.

Python

  1. No Console de APIs do Google, acesse a página do Cloud Run:

    Acessar o Cloud Run

    Verifique se o projeto do app do Chat está selecionado.

  2. Clique em Escrever uma função.

  3. Na página Criar serviço, configure a função:

    1. No campo Nome do serviço, insira quickstartchatapp.
    2. Na lista Região, selecione uma região.
    3. Na lista Ambiente de execução, selecione a versão mais recente do Python.
    4. Na seção Autenticação, selecione Exigir autenticação.
    5. Clique em Criar e aguarde o Cloud Run criar o serviço. O console vai redirecionar você para a guia Origem.

  4. Na guia Origem:

    1. Em Ponto de entrada, exclua o texto padrão e insira avatar_app.

    2. Substitua o conteúdo de main.py pelo seguinte código:

      python/avatar-app/main.py
      from typing import Any, Mapping

import flask
import functions_framework

# Command IDs (configure these in Google Chat API)
ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
HELP_COMMAND_ID = 2  # ID for the "Help" quick command


@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
    """Google Cloud Function that handles HTTP requests from Google Chat.

    Args:
        flask.Request: the request

    Returns:
        Mapping[str, Any]: the response
    """
    event = req.get_json(silent=True)

    if event and "appCommandMetadata" in event:
        return handle_app_commands(event)
    else:
        return handle_regular_message(event)


def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}




def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles regular messages (not commands).

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """

    if not event or "user" not in event:
        return "Invalid request."

    message_data = create_message(event["user"])
    return message_data


def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
    """Creates a card message with the user's avatar.

    Args:
        Mapping[str, Any] user: The user who sent the message.

    Returns:
        Mapping[str, Any]: a card with the user's avatar.
    """
    display_name = user.get("displayName", "")
    avatar_url = user.get("avatarUrl", "")

    return {
        "text": "Here's your avatar",
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": {"title": f"Hello {display_name}!"},
                    "sections": [
                        {
                            "widgets": [
                                {"textParagraph": {"text": "Your avatar picture:"}},
                                {"image": {"imageUrl": avatar_url}},
                            ]
                        }
                    ],
                },
            }
        ],
    }

    3. Clique em Salvar e implantar novamente.

Java

  1. No Console de APIs do Google, acesse a página do Cloud Run:

    Acessar o Cloud Run

    Verifique se o projeto do app do Chat está selecionado.

  2. Clique em Escrever uma função.

  3. Na página Criar serviço, configure a função:

    1. No campo Nome do serviço, insira quickstartchatapp.
    2. Na lista Região, selecione uma região.
    3. Na lista Ambiente de execução, selecione a versão mais recente do Java.
    4. Na seção Autenticação, selecione Exigir autenticação.
    5. Clique em Criar e aguarde o Cloud Run criar o serviço. O console vai redirecionar você para a guia Origem.

  4. Na guia Origem:

    1. Em Ponto de entrada, exclua o texto padrão e insira App.
    2. Renomeie src/main/java/com/example/Example.java para src/main/java/AvatarApp.java.

    3. Substitua o conteúdo de AvatarApp.java pelo seguinte código:

      java/avatar-app/src/main/java/AvatarApp.java
      import com.google.api.services.chat.v1.model.CardWithId;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
import com.google.api.services.chat.v1.model.Message;
import com.google.api.services.chat.v1.model.User;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.List;

public class AvatarApp implements HttpFunction {
  private static final Gson gson = new Gson();

  // Command IDs (configure these in Google Chat API)
  private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
  private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);

    if (event.has("appCommandMetadata")) {
      handleAppCommands(event, response);
    } else {
      handleRegularMessage(event, response);
    }
  }

  /**
   * Handles slash and quick commands.
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
    int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

    switch (appCommandId) {
      case ABOUT_COMMAND_ID:
        Message aboutMessage = new Message();
        aboutMessage.setText("The Avatar app replies to Google Chat messages.");
        aboutMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(aboutMessage));
        return;
      case HELP_COMMAND_ID:
        Message helpMessage = new Message();
        helpMessage.setText("The Avatar app replies to Google Chat messages.");
        helpMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(helpMessage));
        return;
    }
  }

  /**
   * Handles regular messages (not commands).
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {

    if (!event.has("user")) {
      response.getWriter().write("Invalid request.");
      return;
    }

    JsonObject user = event.getAsJsonObject("user");
    String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
    String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);
    response.getWriter().write(gson.toJson(message));
  }

  /**
   * Creates a card message with the user's avatar.
   *
   * @param displayName The user's display name.
   * @param avatarUrl   The URL of the user's avatar.
   * @return The card message object.
   */
  private Message createMessage(String displayName, String avatarUrl) {
    return new Message()
        .setText("Here's your avatar")
        .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
                .setName("Avatar Card")
                .setHeader(new GoogleAppsCardV1CardHeader()
                    .setTitle(String.format("Hello %s!", displayName)))
                .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                    new GoogleAppsCardV1Widget()
                        .setTextParagraph(new GoogleAppsCardV1TextParagraph()
                            .setText("Your avatar picture:")),
                    new GoogleAppsCardV1Widget()
                        .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

    4. Substitua o conteúdo de pom.xml pelo seguinte código:

      java/avatar-app/pom.xml
      <project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>gcfv2</groupId>
  <artifactId>avatar-app</artifactId>
  <version>0.0.1</version>
  <name>Avatar App</name>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.1.4</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.12.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20250116-2.0.0</version>
    </dependency>

  </dependencies>

</project>

    5. Clique em Salvar e implantar novamente.

Autorizar o Google Chat a invocar sua função

Para autorizar o Google Chat a invocar sua função, adicione a conta de serviço do Google Chat com o papel Invocador do Cloud Run.

  1. No Console de APIs do Google, acesse a página do Cloud Run:

    Acessar o Cloud Run

  2. Na lista de serviços do Cloud Run, marque a caixa de seleção ao lado da função de recebimento. (Não clique na função em si.)

  3. Clique em Permissões. O painel Permissões será aberto.

  4. Clique em Adicionar principal.

  5. Em Novos principais, digite chat@system.gserviceaccount.com.

  6. Em Selecionar um papel, selecione Cloud Run > Invocador do Cloud Run.

  7. Clique em Salvar.

Configurar o app do Chat

Depois que a função do Cloud Run for implantada, siga estas etapas para transformá-la em um app do Google Chat:

  1. No Console de APIs do Google, acesse a página do Cloud Run:

    Acessar o Cloud Run

    Verifique se o projeto para que você ativou o Cloud Run está selecionado.

  2. Na lista de serviços, clique em quickstartchatapp.

  3. Na página Detalhes do serviço, copie o URL da função.

  4. Pesquise "API Google Chat" e clique em API Google Chat e em Gerenciar.

    Acessar a API Chat

  5. Clique em Configuração e configure o app do Google Chat:

    1. Desmarque a opção Criar este app do Chat como um complemento do Google Workspace. Uma caixa de diálogo será aberta pedindo confirmação. Na caixa de diálogo, clique em Desativar.
    2. Em Nome do app, insira Quickstart App.
    3. No URL do avatar, insira https://developers.google.com/chat/images/quickstart-app-avatar.png.
    4. Em Descrição, insira Quickstart app.
    5. Em Funcionalidade, selecione Participar de espaços e conversas em grupo.
    6. Em Configurações de conexão, selecione URL do endpoint HTTP.
    7. Em Acionadores, selecione Usar um URL de endpoint HTTP comum para todos os acionadores e cole o URL do acionador da função do Cloud Run na caixa.
    8. Em Visibilidade, selecione Disponibilizar este app do Chat para pessoas e grupos específicos no seu domínio e insira seu endereço de e-mail.
    9. Em Registros, selecione Registrar erros no Logging.

  6. Clique em Salvar.

O app do Chat está pronto para receber e responder a mensagens no Chat.

Testar o app do Chat

Para testar o app do Chat, abra um espaço de mensagem direta com o app do Chat e envie uma mensagem:

  1. Abra o Google Chat usando a conta do Google Workspace que você forneceu ao se adicionar como um testador confiável.

    Acessar o Google Chat

  2. Clique em Novo chat.
  3. No campo Adicionar uma ou mais pessoas, digite o nome do app do Chat.

  4. Selecione o app do Chat nos resultados. Uma mensagem direta será aberta.

  5. Na nova mensagem direta com o app, digite Hello e pressione enter.

A resposta do app do Chat contém uma mensagem de card que mostra o nome e a imagem do avatar do remetente, conforme demonstrado na imagem a seguir:

App de chat respondendo com um card que mostra o nome de exibição e a imagem do avatar do remetente

Para adicionar testadores confiáveis e saber mais sobre como testar recursos interativos, consulte Testar recursos interativos para apps do Google Chat.

Resolver problemas

Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra uma mensagem dizendo "Algo deu errado." ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro não apareça na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando o registro de erros para apps do Chat está ativado. Para receber ajuda na visualização, depuração e correção de erros, consulte Resolver e corrigir erros do Google Chat.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, recomendamos que você exclua o projeto do Cloud.

  1. No Console de APIs do Google, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > Gerenciar recursos.

    Acessar o Resource Manager

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em desligar para excluir o projeto.