Criar um app HTTP do Google Chat

Esta página explica como criar um complemento do Google Workspace que funcione no Google Chat usando um serviço HTTP.

Este guia de início rápido mostra como criar um serviço HTTP usando os serviços do Google Cloud. Para criar o app do Chat, você escreve e implanta uma função do Cloud Run que o app do Chat usa para responder à mensagem de um usuário.

Com uma arquitetura HTTP, 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 do 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 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 flexibilidade para 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 implemente uma função do Cloud Run.
  • Configure um complemento do Google Workspace para o app do Chat.
  • Teste o app.

Pré-requisitos

Configure o ambiente

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

  • No console do Google Cloud, ative 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 implemente uma função do Cloud Run

Crie e implemente uma função do Cloud Run que gere 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 do Google Cloud, 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 addonchatapp.
    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/chat/avatar-app/index.js
    import { http } from '@google-cloud/functions-framework';

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleMessage(event) {
  // Stores the Google Chat user as a variable.
  const chatUser = event.messagePayload.message.sender;
  const displayName = chatUser.displayName;
  const avatarUrl = chatUser.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 }
        }]}]
      }
    }]
  };
}
    1. Clique em Salvar e implantar novamente.

Python

  1. No console do Google Cloud, 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 addonchatapp.
    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/chat/avatar-app/main.py
    from typing import Any, Mapping

import flask
import functions_framework

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  # Stores the Google Chat user as a variable.
  chat_user = event["messagePayload"]["message"]["sender"]
  display_name = chat_user.get("displayName", "")
  avatar_url = chat_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 }},
        ]}]
      }
    }]
  }
    1. Clique em Salvar e implantar novamente.

Java

  1. No console do Google Cloud, 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 addonchatapp.
    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 o arquivo Java padrão para src/main/java/com/google/chat/avatar/App.java.
    3. Substitua o conteúdo de App.java pelo seguinte código:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;

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.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 App implements HttpFunction {
  // The ID of the slash command "/about".
  // You must use the same ID in the Google Chat API configuration.
  private static final int ABOUT_COMMAND_ID = 1;

  private static final Gson gson = new Gson();

  /**
   * Handle requests from Google Workspace add on
   * 
   * @param request the request sent by Google Chat
   * @param response the response to be sent back to Google Chat
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    JsonObject chatEvent = event.getAsJsonObject("chat");
    Message message;
    if (chatEvent.has("appCommandPayload")) {
      message = handleAppCommand(chatEvent);
    } else {
      message = handleMessage(chatEvent);
    }
    JsonObject createMessageAction = new JsonObject();
    createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
    JsonObject chatDataAction = new JsonObject();
    chatDataAction.add("createMessageAction", createMessageAction);
    JsonObject hostAppDataAction = new JsonObject();
    hostAppDataAction.add("chatDataAction", chatDataAction);
    JsonObject dataActions = new JsonObject();
    dataActions.add("hostAppDataAction", hostAppDataAction);
    response.getWriter().write(gson.toJson(dataActions));
  }

  /**
   * Handles an APP_COMMAND event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleAppCommand(JsonObject event) throws Exception {
    switch (event.getAsJsonObject("appCommandPayload")
      .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
      case ABOUT_COMMAND_ID:
        return new Message()
          .setText("The Avatar app replies to Google Chat messages.");
      default:
        return null;
    }
  }

  /**
   * Handles a MESSAGE event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleMessage(JsonObject event) throws Exception {
    // Stores the Google Chat user as a variable.
    JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
    String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
    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)))))))));
  }
}

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

    java/chat/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/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.chat</groupId>
  <artifactId>avatar-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>17</maven.compiler.target>
    <maven.compiler.source>17</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.1.4</version>
    </dependency>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.9.1</version>
    </dependency>
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20230115-2.0.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
        <excludes>
          <exclude>.google/</exclude>
        </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
    1. Clique em Salvar e implantar novamente.

A página de detalhes do serviço do Cloud Run é aberta. Aguarde a implantação da função.

Configurar o complemento

Depois que a função do Cloud Run for implantada, siga estas etapas para criar um complemento e implantar o app do Google Chat:

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

    Acessar o Cloud Run

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

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

  3. Na página Detalhes do serviço, copie o URL da função. O URL termina em run.app.

  4. No campo de pesquisa do Google Cloud, pesquise "API Google Chat", depois 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. Em Nome do app, insira Add-on Chat app.
    2. No URL do avatar, insira https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. Em Descrição, insira Add-on Chat app.
    4. Em Funcionalidade, selecione Participar de espaços e conversas em grupo.
    5. Em Configurações de conexão, selecione URL do endpoint HTTP.
    6. 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.
    7. Em Visibilidade, selecione Disponibilizar esse app do Google Chat para pessoas e grupos específicos no seu domínio e insira seu endereço de e-mail.
    8. Em Registros, selecione Registrar erros no Logging.

  6. Clique em Salvar.

  7. Em Configurações de conexão, copie o e-mail da conta de serviço. Você precisa desse e-mail ao autorizar o complemento a invocar sua função.

Em seguida, autorize o app do Chat a invocar a função do Cloud Run.

Autorizar o Google Chat a invocar sua função

Para autorizar o complemento do Google Workspace a invocar sua função, adicione a conta de serviço do complemento do Google Workspace com o papel de Invocador do serviço 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, selecione 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 participantes, insira o endereço de e-mail da conta de serviço do complemento do Google Workspace associada ao app do Chat.

    O endereço de e-mail da conta de serviço está na página de configuração da API Chat, em Configurações de conexão > URL do endpoint HTTP > E-mail da conta de serviço:

    Acessar a configuração da API Chat

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

  7. 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 mensagem do app do Chat contém um 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 seja exibida 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 do Chat está ativado. Para receber ajuda para 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.

  1. No console do Google Cloud, 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 Encerrar para excluir o projeto.