Criar um app de chat com o Google Cloud Functions

Nesta página, explicamos como criar e interagir com um app de chat usando o Google Cloud Functions.

Para criar o aplicativo, escreva e implante uma Função do Cloud que o aplicativo usa para processar uma resposta a um evento de mensagem do Google Chat. A resposta é um cartão que exibe o nome do remetente e a imagem do avatar, conforme demonstrado na imagem a seguir:

O app de chat responde com um card com o nome de exibição e a imagem de avatar do remetente.

Objetivos

  • Configurar o ambiente.
  • Crie e implante uma Função do Cloud.
  • Publique o app no Google Chat.
  • Testar o app.

Pré-requisitos

Configurar 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 e Cloud Pub/Sub.

    Ative as APIs

Crie e implemente uma Função do Cloud

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

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

Node.js

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

    Acesse o Cloud Functions

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

  2. Clique em Criar função.

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

    1. Em Nome da função, digite "QuickStartChatApp".
    2. Em Tipo de acionador, selecione HTTP.

    3. Em "Autenticação", selecione Permitir invocações não autenticadas.

      Para mais informações sobre a autenticação no Google Workspace, consulte Autenticar e autorizar apps de chat e solicitações de API.

    4. Clique em Salvar.

    5. Clique em Próxima.

  4. Em Ambiente de execução, selecione Node.js 10.

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

  6. Em Ponto de entrada, exclua o texto padrão e digite helloChat.

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

    node/avatar-bot/index.js
    /**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

  8. Clique em Implantar.

Python

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

    Acesse o Cloud Functions

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

  2. Clique em Criar função.

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

    1. Em Nome da função, digite "QuickStartChatApp".
    2. Em Tipo de acionador, selecione HTTP.

    3. Em "Autenticação", selecione Permitir invocações não autenticadas.

      Para mais informações sobre a autenticação no Google Workspace, consulte Autenticar e autorizar apps de chat e solicitações de API.

    4. Clique em Salvar.

    5. Clique em Próxima.

  4. Em Ambiente de execução, selecione Python 3.10.

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

  6. Em Ponto de entrada, exclua o texto padrão e digite hello_chat.

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

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

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

  8. Clique em Implantar.

Java

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

    Acesse o Cloud Functions

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

  2. Clique em Criar função.

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

    1. Em Nome da função, digite "QuickStartChatApp".
    2. Em Tipo de acionador, selecione HTTP.

    3. Em "Autenticação", selecione Permitir invocações não autenticadas.

      Para mais informações sobre a autenticação no Google Workspace, consulte Autenticar e autorizar solicitações de app e de API do Chat.

    4. Clique em Salvar.

    5. Clique em Próxima.

  4. Em Ambiente de execução, selecione Java 11.

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

  6. Em Ponto de entrada, exclua o texto padrão e digite HelloChat.

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

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

    java/avatar-bot/src/main/java/HelloChat.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.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 HelloChat 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("message")) {
      response.getWriter().write("Hello! This function must be called from Google Chat.");
      return;
    }

    JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
    String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);

    response.getWriter().write(gson.toJson(message));
  }

  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("previewLink");
    cardWithId.setCard(card);

    Message message = new Message();
    message.setCardsV2(List.of(cardWithId));

    return message;
  }
}

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

    java/avatar-bot/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>cloudfunctions</groupId>
  <artifactId>http-function</artifactId>
  <version>1.0-SNAPSHOT</version>

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

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.1</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 11 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>

  10. Clique em Implantar.

A página do Cloud Functions é aberta, e a função aparece com um indicador de progresso da implantação ao lado do nome da função. Quando o indicador de progresso desaparecer e uma marca de seleção aparecer, a função será implantada.

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 com o Cloud Functions ativado foi selecionado.

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

  3. Na página "Detalhes da função", clique em Acionador.

  4. Em URL do acionador, copie o URL.

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

  6. Selecione Gerenciar.

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

    1. Em Nome do app, insira Quickstart App.
    2. Em URL do avatar, insira https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. Em Descrição, digite Quickstart app.
    4. Em Funcionalidade, selecione Receber mensagens individuais, Participar de espaços e conversas em grupo e Registrar erros no Cloud Logging.
    5. Em Configurações de conexão, selecione URL do aplicativo e cole o URL do acionador do Cloud Functions na caixa.
    6. Em Permissões, selecione Pessoas e grupos específicos no seu domínio e digite seu endereço de e-mail.

  8. Clique em Salvar.

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

Testar o app Chat

Para testar o app Chat, envie uma mensagem direta para ele:

  1. Abra o Google Chat.
  2. Para enviar uma mensagem direta para o app, clique em Iniciar um chat e, na janela exibida, clique em Encontrar apps.
  3. Na caixa de diálogo Localizar apps, procure "App de início rápido".
  4. Para abrir uma mensagem direta com o aplicativo, encontre o Guia de início rápido e clique em Adicionar > Bate-papo.
  5. Na mensagem direta, digite Hello e pressione enter.

O app retorna um card com o nome de exibição e a imagem de avatar.

Próximas etapas

Para resolver problemas e depurar o app Chat, consulte estas páginas:

  • Durante a criação do app Chat, talvez seja necessário depurá-lo lendo os registros de erro do app. Para ler os registros, no console do Google Cloud, acesse o Explorador de registros.
  • Resolver problemas.

Para adicionar mais funcionalidades ao app Chat, consulte estes guias:

  • Criar cards interativos: as mensagens de card são compatíveis com um layout definido, elementos interativos de IU, como botões, e rich media, como imagens. Use mensagens de cartão para apresentar informações detalhadas, coletar informações dos usuários e orientá-los a dar o próximo passo.
  • Suporte a comandos de barra: os comandos de barra permitem registrar e anunciar comandos específicos que os usuários podem dar ao app digitando um comando que começa com uma barra (/), como /help.
  • Caixas de diálogo para iniciar: as caixas de diálogo são interfaces baseadas em janelas que seu app pode abrir para interagir com o usuário. Vários cartões podem ser agrupados em sequência, o que ajuda os usuários a concluir processos de várias etapas, como o preenchimento de dados de formulários.

Para saber mais sobre a API Google Chat, consulte a documentação de referência.