Criar um app HTTP do Google Chat

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

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

No diagrama anterior, um usuário que interage com um app de chat HTTP 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 para um servidor da Web que é um sistema local ou de nuvem que contém a lógica do app de chat.
3. Opcionalmente, a lógica do app de chat pode ser integrada a serviços do Google Workspace (como Agenda e Folhas), outros serviços do Google (como o Maps, o YouTube e o Vertex AI) ou outros serviços da Web (como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de passagens).
4. O servidor da Web envia uma resposta HTTP de volta ao serviço do app Chat.
5. A resposta é enviada ao usuário.
6. Opcionalmente, o app de 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 de chat podem ser criados usando diferentes linguagens de programação.

Objetivos

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

Pré-requisitos

• Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
• Ter um projeto do Google Cloud com o faturamento ativado. Para verificar se o faturamento está ativado em um projeto, consulte Verificar o status de faturamento dos seus projetos. Para criar um projeto e configurar o faturamento, consulte Criar um projeto do Google Cloud.

Configure o ambiente

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

• No console do Google Cloud, ative as APIs Google Chat, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry e Cloud Run.

  Ativar as APIs

Crie e implemente uma Função do Cloud

Crie e implante uma função do Cloud que gere uma card de 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 no app Chat, siga estas etapas:

Node.js

1. No console do Google Cloud, acesse a página Cloud Functions:

   Acesse o Cloud Functions

   Verifique se o projeto do app de chat está selecionado.

2. Clique em Criar função.

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

   1. Em Ambiente, selecione Função do Cloud Run.
   2. Em Nome da função, insira QuickStartChatApp.
   3. Em Região, selecione uma região.
   4. Em "Autenticação", selecione Exigir autenticação.
   5. Clique em Próxima.

4. Em Ambiente de execução, selecione a versão mais recente do Node.js.

5. Em Código-fonte, selecione Editor in-line.

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

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

   node/avatar-app/index.js

   Ver no GitHub
   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}},
             ],
           }],
         },
       }],
     };
   }

8. Clique em Implantar.

Python

1. No console do Google Cloud, acesse a página Cloud Functions:

   Acesse o Cloud Functions

   Verifique se o projeto do app de chat está selecionado.

2. Clique em Criar função.

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

   1. Em Ambiente, selecione Função do Cloud Run.
   2. Em Nome da função, insira QuickStartChatApp.
   3. Em Região, selecione uma região.
   4. Em "Autenticação", selecione Exigir autenticação.
   5. Clique em Próxima.

4. Em Ambiente de execução, selecione a versão mais recente do Python.

5. Em Código-fonte, selecione Editor in-line.

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

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

   python/avatar-app/main.py

   Ver no GitHub
   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}},
                               ]
                           }
                       ],
                   },
               }
           ],
       }

8. Clique em Implantar.

Java

1. No console do Google Cloud, acesse a página Cloud Functions:

   Acesse o Cloud Functions

   Verifique se o projeto do app de chat está selecionado.

2. Clique em Criar função.

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

   1. Em Ambiente, selecione Função do Cloud Run.
   2. Em Nome da função, insira QuickStartChatApp.
   3. Em Região, selecione uma região.
   4. Em "Autenticação", selecione Exigir autenticação.
   5. Clique em Próxima.

4. Em Ambiente de execução, selecione a versão mais recente do Java.

5. Em Código-fonte, selecione Editor in-line.

6. Em Ponto de entrada, exclua o texto padrão e insira App.

7. O src/main/java/com/example/Example.java foi renomeado como src/main/java/AvatarApp.java.

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

   java/avatar-app/src/main/java/AvatarApp.java

   Ver no GitHub
   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)))))))));
     }
   }

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

   java/avatar-app/pom.xml

   Ver no GitHub
   <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>

10. Clique em Implantar.

A página de detalhes do Cloud Functions é aberta, e sua função aparece com dois indicadores de progresso: um para o build e outro para o serviço. Quando os dois indicadores de progresso desaparecem e são substituídos por uma marca de seleção, a função é implantada e fica pronta.

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 do Google Cloud, 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 é aberto.

4. Clique em Adicionar principal.

5. Em Novos principais, digite [e-mail].

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

7. Clique em Salvar.

Publicar o app no Google Chat

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

1. No console do Google Cloud, clique em Menu > Cloud Functions.

   Acesse o Cloud Functions

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

2. Na lista de funções, clique em QuickStartChatApp.

3. Clique na guia Gatilhos.

4. Em HTTPS, copie o URL.

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

   Acessar a API Chat

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

   1. Em Nome do app, insira Quickstart App.
   2. No URL do avatar, digite https://developers.google.com/chat/images/quickstart-app-avatar.png.
   3. Em Descrição, insira Quickstart app.
   4. Em Funcionalidade, selecione Receber mensagens individuais e Participar de espaços e conversas em grupo.
   5. Em Configurações de conexão, selecione URL do endpoint HTTP e cole o URL do gatilho da função do Cloud na caixa.
   6. Em Público-alvo de autenticação, selecione URL do endpoint HTTP.
   7. Em Visibilidade, selecione Disponibilize o app Google Chat para pessoas e grupos específicos no seu domínio e digite seu endereço de e-mail.
   8. Em Registros, selecione Registrar erros no Logging.

7. Clique em Salvar.

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

Testar o app Chat

Para testar seu 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ê informou ao se adicionar como um testador confiável.

   Acesse o Google Chat

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

4. Selecione o app Chat nos resultados. Uma mensagem direta é aberta.

   Observação:se o app de chat não aparecer na lista de resultados, verifique se você incluiu sua conta do Google Workspace nas configurações de Visibilidade da página Configuração da API Chat no console do Google Cloud.
5. Na nova mensagem direta com o app, digite Hello e pressione enter.

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

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 do Google Chat ou um card retorna um erro, a interface do Chat mostra uma mensagem informando que "Ocorreu um erro". 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 o card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps de chat estiver ativado. Para saber como visualizar, depurar e corrigir 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.

Cuidado:excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL em appspot.com, exclua os recursos selecionados dentro do projeto em vez de excluir o projeto inteiro.

Se você planeja conferir vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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

   Acesse 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 Encerrar para excluir o projeto.

Temas relacionados

• Para adicionar mais recursos ao seu app de chat, consulte o seguinte:

  • Criar mensagens de cards interativos
  • Responder a comandos de barra
  • Abrir e responder a caixas de diálogo

• Escolher uma arquitetura de app do Chat

• Verificar solicitações do Google Chat