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:

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:

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:

   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.

   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:

      • 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.

Configurar o app do Chat usando a API Google Workspace Add-ons

Em vez de configurar o app do Chat manualmente no console do Google Cloud, use o projeto na nuvem do Google Cloud inscrito no Programa de prévia para desenvolvedores do Google Workspace para ler e atualizar de forma programática a configuração de um app do Chat criado como um complemento do Google Workspace usando o recurso chatAppConfig na Google Workspace add-ons API.

chatAppConfig é um recurso Singleton que sempre existe para cada projeto na nuvem. Antes de salvar uma configuração pela primeira vez, o recurso contém uma configuração vazia, que também é o que GetChatAppConfig retorna se você ler o recurso antes de salvar pela primeira vez. Como o recurso já existe, não é necessário criá-lo separadamente. Use UpdateChatAppConfig para salvar a configuração inicial e atualizar uma configuração atual.

Pré-requisitos e autenticação

Antes de chamar GetChatAppConfig ou UpdateChatAppConfig, conclua os seguintes pré-requisitos:

1. Inscreva seu projeto do Google Cloud no Programa de prévia para desenvolvedores do Google Workspace.
2. Ative a API Google Workspace Add-ons (gsuiteaddons.googleapis.com) no seu projeto na nuvem. Se quiser, você pode ativar a API Google Chat (chat.googleapis.com) para ver ou atualizar a configuração do app do Chat no console do Google Cloud ou chamar a API Chat.
3. Autentique-se como um usuário humano com uma credencial do OAuth 2.0 que inclua o escopo https://www.googleapis.com/auth/cloud-platform. A autenticação de conta de serviço não é compatível com os métodos chatAppConfig.
4. Verifique se o usuário autenticado tem as permissões necessárias do Identity and Access Management (IAM) no projeto na nuvem de destino:
   • gsuiteaddons.chatAppConfigs.get e chat.bots.get para ler a configuração (GetChatAppConfig).
   • gsuiteaddons.chatAppConfigs.update e chat.bots.update para atualizar a configuração (UpdateChatAppConfig).
5. Se você usa uma biblioteca de cliente, baixe a biblioteca de cliente da prévia para desenvolvedores com sua conta registrada da prévia para desenvolvedores.

Atualizar a configuração de um app do Chat

Para configurar um app do Chat pela primeira vez ou atualizar uma configuração, envie uma solicitação PATCH (UpdateChatAppConfig) para o recurso singleton chatAppConfig do seu projeto na nuvem:

• Para o salvamento inicial em um projeto na nuvem com um chatAppConfig vazio, são necessários displayName (3 a 25 caracteres) e description (1 a 40 caracteres). Se você omitir interactiveFeatureConfig no salvamento inicial, o app do Chat será configurado como não interativo.
• Para atualizações subsequentes, use o parâmetro de consulta opcional updateMask para especificar os campos separados por vírgulas a serem atualizados (ou omita updateMask para atualizar todos os campos fornecidos). A atualização de um campo repetido (appCommands, urlPatterns ou allowlistedTestingPrincipals) substitui toda a lista.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Substitua o seguinte no URL, no cabeçalho e no corpo da solicitação:

• PROJECT_NUMBER: o número do projeto na nuvem que hospeda seu app do Chat.
• ACCESS_TOKEN: um token de acesso do OAuth 2.0 de usuário autorizado com o escopo https://www.googleapis.com/auth/cloud-platform.
• USER_EMAIL: um endereço de e-mail ou Grupo do Google da sua organização do Google Workspace para incluir na lista de permissões para testar o app do Chat (por exemplo, seu próprio endereço de e-mail).
• Os campos de configuração de exemplo no corpo da solicitação (como displayName, description, avatarUri e interactiveFeatureConfig, incluindo a configuração do endpoint, os comandos, os padrões de URL de prévia de link e os principais de teste) com os valores do seu app do Chat. Para detalhes sobre todos os campos e opções de endpoint compatíveis, consulte a referência REST de projects.chatAppConfig e projects.chatAppConfig.patch.

Receber uma configuração de app do Chat

Para ler a configuração atual do app do Chat em um projeto na nuvem, chame GetChatAppConfig. É possível transmitir o parâmetro de consulta opcional view (ChatAppConfigView):

• BASIC (padrão): retorna metadados básicos sem interactiveFeatureConfig.
• FULL: retorna todos os campos de configuração, incluindo interactiveFeatureConfig.

Se a configuração do app do Chat ainda não tiver sido salva para o projeto na nuvem, o método vai retornar um objeto ChatAppConfig vazio.

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

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. Você define essas configurações de instalação no SDK do 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 projects.deployments que você 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. Em vez disso, configure o app do Chat no console do Google Cloud ou use o recurso chatAppConfig na API Google Workspace Add-ons.

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.

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