Configurar a API Google Chat

Cada app do Google Chat que você cria requer um projeto próprio do Google Cloud com a API Chat ativada e configurada.

Para fazer chamadas de API somente leitura com autenticação do usuário, como receber espaços e listar mensagens, basta ativar a API e criar um cliente OAuth.

Para realizar chamadas de API de criação, atualização e exclusão ou para implantar e testar um app interativo do Chat (criado como um complemento do Google Workspace que estende o Chat), você também precisa configurar a API Chat. Nas configurações da API Chat, você especifica todos os detalhes sobre o app do Chat, incluindo o nome de exibição, o avatar, os endpoints de implantação e os recursos interativos.

Pré-requisitos

• Uma conta Business ou Enterprise do Google Workspace com acesso ao Google Chat.
• Crie um projeto do Google Cloud.
• Configure a tela de permissão OAuth.
• Ative a API Google Chat.

Escolha um nome de exibição, um avatar e uma descrição para o app do Chat

Ao ativar a API Chat, você configura os detalhes do seu app do Chat que aparecem para os usuários no Chat, incluindo um nome de exibição, um avatar e uma descrição. Esses detalhes só aparecem no Chat. Para publicar seu app do Chat no Marketplace, você também precisa especificar os detalhes que aparecem na página de detalhes do app do Chat no Marketplace.

Antes de configurar um app do Chat, prepare as seguintes informações:

Campo	Descrição	Formato
Nome do app	O nome de exibição do app do Chat.	Até 25 caracteres alfanuméricos
URL do avatar	A imagem que aparece como o avatar do app do Chat.	Um URL HTTPS que aponta para uma imagem gráfica quadrada (PNG ou JPEG). O tamanho recomendado é de 256 x 256 pixels ou mais.
Descrição	Uma breve descrição da finalidade do app do Chat.	Até 40 caracteres alfanuméricos

O nome, o avatar e a descrição do app do Chat são mostrados aos usuários na interface do Chat. Para algumas solicitações de gravação da API Chat, o Chat usa essas informações para atribuir as ações que um app do Chat realiza no Chat.

Por exemplo, se você chamar o método spaces.create(), o Chat vai incluir o nome do app do Chat na descrição de quem criou o espaço, como mostrado na imagem a seguir:

Figura 1. A mensagem de atribuição que o Chat mostra quando o método spaces.create() é usado para criar um espaço em nome de um usuário.

Para interagir com os apps do Chat, os usuários também veem ou usam essas informações das seguintes maneiras:

• @mencione o app do Chat para adicioná-lo a um espaço ou enviar uma mensagem.
• Encontre e inicie uma mensagem direta com o app do Chat. No menu Apps, as mensagens diretas mostram o nome e o avatar do app do Chat.
• Na barra de escrita, os usuários podem navegar pelos apps do Chat e ver o nome, o avatar e a descrição deles.

Configurar o app do Chat no console do Google Cloud

Quando tiver os detalhes do app do Chat, abra seu projeto na nuvem e configure a API Chat:

1. No console do Google Cloud, acesse a página da API Chat e clique na página Configuração:

   Acesse a página de configuração da API Chat

2. Em Informações do aplicativo, preencha os campos Nome do app, URL do avatar e Descrição.

3. Opcional: no menu Sintaxe de marcação, selecione a sintaxe de marcação padrão (Markdown ou Chat) para as mensagens do seu app do Chat. Para saber mais sobre a formatação de texto e como o Chat determina a sintaxe de marcação para solicitações de API, consulte Formatar mensagens.

4. Em Recursos interativos, configure se o app do Chat responde às interações do usuário:

   Observação: se o app do Chat apenas chamar a API Chat e não receber nem responder às interações do usuário, deixe a opção Ativar recursos interativos desativada e pule para a próxima etapa.

   Para criar um app do Chat interativo, ative a opção Ativar recursos interativos e faça o seguinte:

   1. Em Funcionalidade:
      • Opcional: selecione Suporte à página inicial do app para exibir um card de página inicial na guia Início das mensagens diretas individuais com o app do Chat.
      • Selecione Participar de espaços e conversas em grupo para disponibilizar seu app do Chat para instalação e uso. Por padrão, os usuários podem instalar e trocar mensagens com o app do Chat em um espaço dedicado entre o usuário e o app do Chat. Os usuários também podem adicionar e interagir com o app do Chat em espaços com várias pessoas.

   2. Em Configurações de conexão, selecione a arquitetura que você quer usar para receber objetos de evento do Chat:

      • Para usar um serviço HTTP, selecione URL do endpoint HTTP e forneça um URL.
      • Para usar um projeto do Google Apps Script, selecione Apps Script e forneça um ID de implantação para o projeto.
      • Para usar um agente do Dialogflow, selecione Dialogflow, selecione Dialogflow CX ou Dialogflow ES e forneça o nome do recurso do agente.
      • Para usar o Pub/Sub, selecione Cloud Pub/Sub e insira o nome do tópico.
      Aviso :se um ID de implantação do Apps Script já estiver preenchido, o projeto na nuvem estará conectado a um complemento do Google Workspace. Se você atualizar o ID de implantação na API Chat, ele será atualizado para o complemento e poderá afetar sua listagem no Google Workspace Marketplace. Para revisar a configuração do complemento, consulte Configurar seu app no SDK do Google Workspace Marketplace.

   3. Opcional: para rotear objetos de evento para endpoints ou funções específicos, acesse Configurações de conexão > Acionadores e forneça ou atualize os endpoints ou funções de callback para os seguintes acionadores do Chat:

      Observação: no Apps Script, se você não atualizar os acionadores, será necessário implementar as funções de callback padrão que são preenchidas nesta seção (como onMessage, onAddedToSpace, onRemovedFromSpace, onAppCommand e onAppHome).
      • Página inicial do app (se a opção Suporte à página inicial do app estiver ativada): um usuário abre a guia Página inicial em uma mensagem direta individual com o app do Chat.
      • Adicionado ao espaço: um usuário adiciona o app do Chat a uma conversa em grupo ou espaço ou instala o app do Chat para mensagens individuais.
      • Mensagem: um usuário envia uma mensagem para o app do Chat. Por exemplo, um usuário envia uma mensagem direta para o app do Chat ou menciona o app do Chat com @em um espaço com várias pessoas.
      • Removido do espaço: um usuário desinstala ou remove o app do Chat de um espaço.
      • Comando do app: um usuário invoca um comando rápido, um comando de barra ou uma ação de mensagem do app do Chat.

   4. Opcional: adicione outros recursos interativos, como comandos iniciais, comandos (comandos rápidos, comandos de barra e ações de mensagem) ou visualizações de link.

   5. Em Visibilidade, especifique seu endereço de e-mail para poder instalar e testar o app do Chat antes de publicar no Google Workspace Marketplace. É possível especificar até cinco pessoas ou um ou mais Grupos do Google da sua organização do Google Workspace.

5. Opcional: em Registros, marque a caixa de seleção Registrar erros no Logging para usar o Google Cloud Logging. Para mais informações, consulte Consultar registros de erros de apps do Chat.

6. Clique em Salvar.

Depois de salvar a configuração, qualquer pessoa que você tenha especificado na configuração de Visibilidade da API Chat poderá instalar, testar ou usar o app do Chat. Para começar a testar e depurar o app do Chat, consulte Testar recursos interativos para apps do Google Chat.

Considerações sobre os complementos do Google Workspace

Os apps do Chat exigem uma configuração diferente em comparação com os complementos do Google Workspace que estendem outros aplicativos do Google Workspace. Se o complemento estender outros aplicativos do Google Workspace, considere os seguintes requisitos para configurar o app do Chat:

• Tanto os usuários quanto os administradores do Google Workspace precisam conseguir instalar seu complemento pelo Marketplace. Defina essas configurações de instalação no SDK do Google Workspace Marketplace.
• Os apps do Chat não usam o nome e o logotipo que você configura para outros aplicativos do Google Workspace no objeto addons.common do manifesto.
• Para complementos publicados no Google Workspace Marketplace, não é possível salvar um rascunho das mudanças nas configurações da API Google Chat. Depois que você atualizar e salvar as configurações da API Chat, o app do Chat atualizado vai ficar disponível imediatamente para todos os usuários. Para atualizar sua listagem do Marketplace, crie um rascunho antes de enviar as mudanças.
• Se você criou o complemento usando o Apps Script:
  • Use o mesmo ID de implantação do Apps Script que você usa para o restante da configuração do complemento.
  • Não é possível usar o editor do Apps Script para instalar implantações de teste no Chat. Em vez disso, você precisa instalá-los diretamente na interface do Chat.
• Se você criou o complemento usando um serviço HTTP, omita os detalhes de configuração do app do Chat no manifesto e nas implantações que criar usando a API de complementos do Google Workspace. As implantações HTTP especificadas no SDK do Google Workspace Marketplace são usadas apenas para outros aplicativos do Google Workspace.

Conceder permissão para outras pessoas configurarem a API Chat

Você pode conceder acesso à página de configuração do app do Chat a usuários específicos atribuindo a eles o papel do Google Cloud Identity Access Management (IAM) de Proprietário de apps do Chat ou Leitor de apps do Chat. Os usuários com esses papéis não podem acessar a página de configuração dos apps do Chat usando o painel APIs e serviços, mas podem acessar a página de configuração acessando o console do Google Cloud para o projeto na nuvem host do app do Chat da seguinte maneira:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

Em que PROJECT_ID é o ID do projeto do Google Cloud que hospeda o app do Chat.

Os usuários com papéis de projeto também podem acessar a página de configuração do app.

Os usuários com papéis personalizados que contêm as permissões resourcemanager.projects.(get|update) não podem acessar a configuração do app do Chat. Para papéis personalizados, use as permissões chat.bots.(get|update).

Temas relacionados

• Escolher uma arquitetura de app do Chat
• Receber e responder às interações do usuário
• Testar recursos interativos para apps do Google Chat

Apps do Chat que não são complementos: configurar a API Google Chat

Se você mantém um app do Chat que não é um complemento do Google Workspace, sua configuração usa um único endpoint para todos os eventos de interação, em vez de acionadores por evento:

1. No console do Google Cloud, acesse a página de configuração da API Chat:

   Acesse a página de configuração da API Chat

2. Em Recursos interativos, ative a opção Ativar recursos interativos.

3. Desmarque a opção Criar este app do Chat como um complemento do Google Workspace. Uma caixa de diálogo será aberta pedindo para você confirmar. Na caixa de diálogo, clique em Desativar.

4. Em Funcionalidade, selecione Suporte à página inicial do app ou Participar de espaços e conversas em grupo, conforme necessário.

5. Em Configurações de conexão, especifique um único endpoint para seu app do Chat (URL do endpoint HTTP, ID de implantação do Apps Script, nome do tópico do Cloud Pub/Sub ou Dialogflow).

6. Configure os campos opcionais Comandos, Prévias de links, Visibilidade e Registros e clique em Salvar.

Para fazer upgrade de um app do Chat que não é um complemento para um complemento do Google Workspace que estende o Google Chat, consulte Converter um app do Google Chat em um complemento do Google Workspace.