Esta página foi traduzida pela API Cloud Translation.

Receber e responder a interações com o app Google Chat

Esta página descreve como seu app do Google Chat pode receber e responder às interações do usuário, também conhecidas como eventos de interação com o app do Google Chat.

Um evento de interação com o app do Google Chat representa qualquer ação realizada por um usuário para invocar ou interagir com um app do Chat, como @mencionar um app do Chat ou adicioná-lo a um espaço. Quando os usuários interagem com um app do Chat, o Google Chat envia um evento de interação a ele. O app do Chat pode usar o evento para processar a interação e criar uma resposta.

Por exemplo, os apps de chat usam eventos de interação para fazer o seguinte:

Exemplo de um evento de interação	Resposta típica de um app do Chat
Um usuário invoca um app do Chat @mencionando-o ou usando um comando de barra.	O app do Chat processa o que a mensagem diz para criar uma mensagem. Por exemplo, um app do Chat responde ao comando `/about` com uma mensagem que explica as tarefas que o app do Chat pode fazer.
Um usuário adiciona um app do Chat a um espaço.	O app do Chat envia uma mensagem de integração que explica o que ele faz e como os usuários no espaço podem interagir com ele.
Um usuário remove um app do Chat de um espaço.	O app do Chat remove todas as notificações recebidas configuradas para o espaço (por exemplo, a exclusão de um webhook) e limpa qualquer armazenamento interno.
Um usuário clica em um botão em um card ou em uma caixa de diálogo enviada pelo app do Chat.	O app do Chat processa e armazena todos os dados enviados pelo usuário ou retorna outro cartão ou caixa de diálogo.

Para cada tipo de interação do usuário, o Google Chat envia um tipo diferente de evento de interação. Por exemplo, o Google Chat usa o tipo de evento MESSAGE para qualquer interação em que um usuário invoca o app do Chat em uma mensagem. Para saber mais detalhes, consulte Tipos de evento de interação com o app do Google Chat.

Esta página explica como fazer o seguinte:

Configure o app do Chat para receber eventos.
Processe o evento de interação na sua infraestrutura.
Se apropriado, responda aos eventos de interação.

Receber eventos de interação com o app do Chat

Nesta seção, descrevemos como receber e processar eventos de interação no seu app do Chat.

Configurar o app do Chat para receber eventos de interação

Nem todos os apps de chat são interativos. Por exemplo, os webhooks de entrada só podem enviar mensagens de saída e não podem responder aos usuários. Se você estiver criando um app do Chat interativo, escolha um endpoint que permita que seu app do Chat receba, processe e responda a eventos de interação. Para saber mais sobre como projetar seu app do Chat, consulte Arquiteturas de implementação de apps do Chat.

Se você criou um app do Chat interativo, configure a API Google Chat para que o Google Chat envie eventos de interação:

No console do Google Cloud, abra a página da API Google Chat:
Acessar a página da API Google Chat
Clique na guia Configuração.
Na seção Recursos interativos, clique no botão Ativar recursos interativos.
Em Funcionalidade, marque uma ou as duas caixas de seleção a seguir:
1. Receber mensagens individuais: permite que os usuários interajam com seu app do Chat em espaços de mensagens diretas (DM). Seu app do Chat recebe eventos de interação sempre que um usuário envia uma mensagem no espaço de mensagem direta.
2. Participar de espaços e conversas em grupo: permite que os usuários adicionem e removam seu app do Chat de espaços com mais de uma pessoa. O app do Chat recebe eventos de interação sempre que é adicionado ou removido do espaço e sempre que os usuários @mencionam ou usam um comando de barra no espaço.
Em Configurações de conexão, especifique para onde o Google Chat envia os eventos de interação do app do Chat.
Opcional: em Comandos de barra, adicione e configure um ou mais comandos de barra. Para mais informações, consulte Configurar comandos de barra.
Opcional: em Visualizações de links, adicione e configure um ou mais padrões de URL que o app do Chat pode visualizar. Para mais informações, consulte Links de visualização.
Clique em Salvar.

Agora seu app do Chat está configurado para receber eventos de interação do Google Chat.

Autenticar solicitações do Google Chat

Para apps criados em endpoints HTTP, esta seção explica como verificar se as solicitações para o endpoint vêm do Google Chat.

Para enviar eventos de interação ao endpoint do app do Chat, o Google faz solicitações ao serviço. Para verificar se a solicitação vem do Google, o Google Chat inclui um token do portador no cabeçalho Authorization de todas as solicitações HTTPS para o endpoint. Por exemplo:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

A string AbCdEf123456 no exemplo acima é o token de autorização do portador. Esse é um token criptográfico produzido pelo Google. É possível verificar o token do portador usando uma biblioteca de cliente de código aberto da API do Google:

Java: https://github.com/google/google-api-java-client
Python: https://github.com/google/google-api-python-client
.NET: https://github.com/google/google-api-dotnet-client

No caso dos tokens do portador enviados nas solicitações do Google Chat, o emissor é chat@system.gserviceaccount.com e o campo audience é definido como o número do projeto do Google Cloud que você usou para criar seu app do Chat. Por exemplo, se o número do projeto na nuvem do seu app do Chat for 1234567890, o campo audience no token do portador será 1234567890.

Se o token não for verificado para o app do Chat, o serviço deve responder à solicitação com um código de resposta HTTPS 401 (Unauthorized).

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Processar novas tentativas de chamada HTTP para o serviço

Se uma solicitação HTTPS para seu serviço falhar (como tempo limite, falha temporária de rede ou código de status HTTPS não 2xx), o Google Chat tenta a entrega duas vezes, com um atraso de pelo menos 10 segundos entre cada nova tentativa. Como resultado, um app do Chat pode receber a mesma mensagem até três vezes em determinadas situações. Se a solicitação for concluída com êxito, mas retornar um payload de mensagem inválido, o Google Chat não tentará repetir a solicitação.

Processar ou responder a eventos de interação

Nesta seção, explicamos como os apps do Google Chat podem processar e responder a eventos de interação.

Depois que seu app do Chat recebe um evento de interação do Google Chat, ele pode responder de várias maneiras. Em muitos casos, os apps de chat interativos respondem ao usuário com uma mensagem. O app Google Chat também pode procurar algumas informações em uma fonte de dados, registrar as informações do evento de interação ou qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app Google Chat.

Para cada evento de interação, os apps de chat recebem um corpo da solicitação, que é o payload JSON que representa o evento. É possível usar as informações para processar uma resposta. Para ver exemplos de payloads de eventos, consulte Tipos de eventos de interação com o app do Chat.

O diagrama a seguir demonstra como o app Google Chat normalmente processa ou responde a diferentes tipos de eventos de interação:

Arquitetura de como os apps do Google Chat processam eventos de interação.

Responda em tempo real

Com os eventos de interação, os apps de chat podem responder em tempo real ou de forma síncrona. As respostas síncronas não exigem autenticação.

Para criar respostas síncronas a eventos de interação, consulte os seguintes guias:

Para responder de maneira síncrona, um app do Chat precisa responder em até 30 segundos, e a resposta precisa ser postada no espaço em que a interação ocorreu. Caso contrário, o app do Chat poderá responder de maneira assíncrona.

Responder de forma assíncrona

Às vezes, os apps do Chat precisam responder a um evento de interação após 30 segundos ou executar tarefas fora do espaço em que o evento de interação foi gerado. Por exemplo, um app do Chat pode precisar responder ao usuário depois de concluir uma tarefa de longa duração. Nesse caso, os apps de chat podem responder de forma assíncrona chamando a API Google Chat.

Para criar uma mensagem usando a API Chat, consulte Criar uma mensagem. Para orientações sobre como usar outros métodos da API Chat, consulte a Visão geral da API Chat.