Criar um app HTTP do Google Chat

Nesta página, explicamos como criar um complemento do Google Workspace que funciona no Google Chat usando um serviço HTTP.

Neste guia de início rápido, mostramos como criar um serviço HTTP usando os serviços do Google Cloud. Para criar o app do Chat, escreva e implante 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 se integrar ao Google Cloud ou a 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 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 a um servidor da Web, que é um sistema na nuvem ou local que contém a lógica do app Chat.
  3. Opcionalmente, a lógica do app 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 tíquetes).
  4. O servidor da Web envia uma resposta HTTP de volta ao serviço do app Chat no Chat.
  5. A resposta é enviada ao usuário.
  6. Opcionalmente, o app 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 atuais que já existem no seu sistema, porque esses apps de chat podem ser projetados usando diferentes linguagens de programação.

Objetivos

  • Prepare o ambiente.
  • Crie e implante uma função do Cloud Run.
  • Configure um complemento do Google Workspace para o app Chat.
  • Teste o app.

Pré-requisitos

Configure o ambiente

Antes de usar as APIs do Google, é necessário 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 Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry e Cloud Run.

    Ativar as APIs

Criar e implantar uma função do Cloud Run

Crie e implante 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 Chat recebe uma mensagem, ele executa a função e responde com o card.

Para criar e implantar a função do seu 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 seu app do Chat está selecionado.

  2. Clique em Escrever uma função.

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

    1. No campo Nome da conta de 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 redireciona 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:
    /**
 * Google Cloud Run function that responds to messages sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
import { http } from '@google-cloud/functions-framework';

http('avatarApp', (req, res) => {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }

    // Stores the Google Chat event as a variable.
    const chatMessage = req.body.chat.messagePayload.message;

    // Replies with the sender's avatar in a card.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        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. Substitua o conteúdo de package.json pelo seguinte código:
    {
  "name": "avatar-app",
  "version": "1.0.0",
  "description": "Google Chat Avatar App",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
    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 seu app do Chat está selecionado.

  2. Clique em Escrever uma função.

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

    1. No campo Nome da conta de 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 redireciona 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:
    from typing import Any, Mapping

import flask
import functions_framework

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

    Args:
        flask.Request: the request

    Returns:
        Mapping[str, Any]: the response
    """
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    # Stores the Google Chat event as a variable.
    chat_message = request_json["chat"]["messagePayload"]["message"]

    # Replies with the sender's avatar in a card.
    display_name = chat_message["sender"]["displayName"]
    avatar_url = chat_message["sender"]["avatarUrl"]
    return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
        "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 seu app do Chat está selecionado.

  2. Clique em Escrever uma função.

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

    1. No campo Nome da conta de 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 redireciona você para a guia Origem.

  4. Na guia Origem:

    1. Em Ponto de entrada, exclua o texto padrão e insira AvatarApp.
    2. Renomeie o arquivo Java padrão para src/main/java/gcfv2/AvatarApp.java.
    3. Substitua o conteúdo de AvatarApp.java pelo seguinte código:
    import java.util.List;

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;

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

    @Override
    public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
        if (request.getMethod().equals("GET") || !body.has("chat")) {
            response.getWriter().write("Hello! This function is meant to be used " +
                "in a Google Chat Space..");
            return;
        }

        // Stores the Google Chat event as a variable.
        JsonObject chatMessage = body.getAsJsonObject("chat")
            .getAsJsonObject("messagePayload").getAsJsonObject("message");

        // Replies with the sender's avatar in a card.
        String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString();
        String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString();
        Message message = createMessage(displayName, avatarUrl);

        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));
    }

    Message createMessage(String displayName, String avatarUrl) {
        GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
        cardHeader.setTitle(String.format("Hello %s!", displayName));

        GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
        textParagraph.setText("Your avatar picture: ");

        GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
        avatarWidget.setTextParagraph(textParagraph);

        GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
        image.setImageUrl(avatarUrl);

        GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
        avatarImageWidget.setImage(image);

        GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
        section.setWidgets(List.of(avatarWidget, avatarImageWidget));

        GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
        card.setName("Avatar Card");
        card.setHeader(cardHeader);
        card.setSections(List.of(section));

        CardWithId cardWithId = new CardWithId();
        cardWithId.setCardId("avatarCard");
        cardWithId.setCard(card);

        Message message = new Message();
        message.setText("Here's your avatar");
        message.setCardsV2(List.of(cardWithId));

        return message;
    }
}

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

    <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.0.4</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.9.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-rev20230115-2.0.0</version>
        </dependency>
    </dependencies>

    <!-- Required for Java functions in the inline editor -->
    <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 Google Chat:

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

    Acessar o Cloud Run

    Verifique se o projeto em que 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, procure "API Google Chat", clique em API Google Chat e em Gerenciar.

    Acessar a API Chat

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

    1. Em Nome do app, insira Add-on Chat app.
    2. Em URL do avatar, digite 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. Copie o e-mail da conta de serviço. Você vai precisar desse e-mail ao autorizar o complemento a invocar sua função.
    7. Em Gatilhos, selecione Usar um URL de endpoint HTTP comum para todos os gatilhos e cole o URL do gatilho da função do Cloud Run na caixa.
    8. 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.
    9. Em Registros, selecione Registrar erros no Logging.

  6. Clique em Salvar.

Em seguida, autorize o app 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 a função 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, 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 participantes, insira o endereço de e-mail da conta de serviço do complemento do Google Workspace associada ao app 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, escolha Cloud Run > Invocador do serviço do Cloud Run.

  7. Clique em Salvar.

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

Testar o app do Chat

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

  1. Abra o Google Chat usando a conta do Google Workspace que você informou ao se tornar um testador de confiança.

    Acessar 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 seu app de chat nos resultados. Uma mensagem direta é aberta.

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

A mensagem do app Chat contém um card que mostra o nome e a imagem do avatar do remetente, como 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 de confiança 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 a mensagem "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 card do Chat produz um resultado inesperado. Por exemplo, uma mensagem do 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 ajuda com a 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 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 excluí-lo.