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 criar, atualizar e excluir chamadas de API ou 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

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 do app 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 do app do Chat, exibida quando os usuários pesquisam apps no Chat. Até 40 caracteres alfanuméricos
Longa Opcional. Uma descrição do que o app do Chat pode fazer, exibida quando os usuários iniciam uma conversa com o app do Chat ou abrem a página inicial de sessões de um agente. No momento, só é possível atualizar a configuração do app usando o console do Google Cloud. Não é possível fazer isso pela API de complementos do Google Workspace. Até 250 caracteres

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:

O app do Google Chat cria um espaço para um usuário.
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 o 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: preencha o campo Descrição longa.

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

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

    Para criar um app do Google 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 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 Chat.
    4. Opcional: adicione outros recursos interativos, como sessões, comandos iniciais, comandos (comandos rápidos, comandos de barra e ações de mensagem) ou visualizações de link.

    5. Em Visibilidade, selecione Disponibilizar este app do Chat para pessoas e grupos específicos e insira os endereços de e-mail de indivíduos ou Grupos do Google na sua organização do Google Workspace:

      • Para instalar e testar o app, insira seu próprio endereço de e-mail.
      • Para compartilhar um app do Chat interno com uma equipe ou com toda a organização sem publicar no Marketplace, insira um ou mais Grupos do Google. Os grupos não têm um limite de participantes. Se o app solicitar escopos chat.app.*, você ainda precisará publicar o app para aprovação do administrador.
      • Se o administrador restringir as instalações do Marketplace aos apps em uma lista de permissões, o console do Google Cloud vai limitar esse campo a cinco endereços de e-mail de usuários individuais para desenvolvimento. A visibilidade do grupo só se aplica depois que um administrador adiciona o app à lista de permissões.
  6. 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.

  7. 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 CLI do Google Cloud

Em vez de usar o console do Google Cloud, é possível visualizar e atualizar a configuração de um app do Chat na linha de comando com a CLI do Google Cloud (CLI gcloud). Por exemplo, é possível configurar um app do Chat usando um script ou manter a configuração em um arquivo armazenado com seu código.

O grupo de comandos gcloud beta workspace-add-ons chat-app-config tem os seguintes comandos:

  • describe: mostra a configuração.
  • update: configura um app do Chat pela primeira vez ou muda a configuração dele.

Os comandos usam o recurso chatAppConfig na API Google Workspace Add-ons.

Antes de começar

  1. Instale a CLI gcloud. Se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.
  2. Faça login na CLI gcloud com sua conta de usuário. Os comandos não são compatíveis com contas de serviço.

    gcloud auth login
  3. Defina o projeto na nuvem do app do Chat como o projeto padrão da CLI gcloud. Use o ID do projeto, porque os comandos não aceitam um número de projeto.

    gcloud config set project PROJECT_ID

    Como alternativa, adicione a flag --project a cada comando.

  4. Ative a API Google Workspace Add-ons no projeto na nuvem:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Verifique se você tem os seguintes papéis do Identity and Access Management (IAM) no projeto na nuvem:

    • Desenvolvedor de complementos do Google Workspace (roles/gsuiteaddons.developer) para ver e atualizar a configuração ou Leitor de complementos do Google Workspace (roles/gsuiteaddons.reader) para apenas ver. Esses papéis incluem as permissões listadas em Pré-requisitos e autenticação.
    • Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer). A CLI gcloud usa o projeto na nuvem como o projeto de cota para as solicitações, o que requer a permissão serviceusage.services.use.

    Os papéis de proprietário e editor incluem todas essas permissões. Os papéis de Proprietário de apps do Chat e Leitor de apps do Chat, que dão acesso à página de configuração no console do Google Cloud, não são suficientes.

Ver a configuração

Para ver a configuração do app do Chat, execute o comando describe:

gcloud beta workspace-add-ons chat-app-config describe

O resultado será assim:

avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
  allowlistedTestingPrincipals:
  - user@example.com
  appCommands:
  - command: /help
    commandId: 1
    commandType: SLASH_COMMAND
    description: Show available commands
  connectionConfig:
    httpEndpointConfig:
      commonUrl: https://example.com/chat
  supportsMultiuserSpaces: true
  urlPatterns:
  - hostPattern: example.com
    pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE

Se o projeto na nuvem ainda não tiver um app do Chat, o comando será bem-sucedido e vai mostrar apenas o campo name da configuração:

name: projects/123456789012/chatAppConfig

Para mudar a saída, adicione uma das seguintes flags:

  • --format=json: mostra a configuração no formato JSON.
  • --view=basic: deixa de fora as configurações de recursos interativos (interactiveFeatureConfig).
  • --format="value(displayName)": mostra apenas o nome de exibição ou uma linha vazia se o projeto na nuvem ainda não tiver um app do Chat. Um app do Chat configurado sempre tem um nome de exibição. Portanto, é possível usar essa flag em um script para verificar se um app do Chat existe.

Atualizar a configuração

Para configurar um app do Chat pela primeira vez ou mudar a configuração dele, execute o comando update. Especifique as configurações com flags ou em um arquivo de configuração. Não é possível combinar os dois em um único comando.

Na primeira vez que você executar o comando para um projeto na nuvem, será necessário especificar pelo menos um nome de exibição e uma descrição. A menos que você defina o estado como desativado, o app do Chat vai ficar ativo assim que o comando for concluído. As pessoas que você listar como testadores poderão encontrar e usar o app.

Usar flags

O exemplo a seguir configura um app do Chat que recebe eventos em um endpoint HTTP:

gcloud beta workspace-add-ons chat-app-config update \
    --display-name="Quickstart App" \
    --description="Quickstart app" \
    --avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
    --http-endpoint-url=HTTP_ENDPOINT_URL \
    --supports-multiuser-spaces \
    --add-allowlisted-testing-principals=USER_EMAIL \
    --error-logging-enabled

Substitua:

  • HTTP_ENDPOINT_URL: o URL HTTPS que recebe objetos de evento do Chat.
  • USER_EMAIL: o endereço de e-mail de uma pessoa ou um grupo na sua organização do Google Workspace que pode instalar e testar o app do Chat, como seu próprio endereço de e-mail.

O comando imprime a configuração atualizada.

A tabela a seguir lista as flags para as configurações na página Configuração da API Chat no console do Google Cloud. Para detalhes sobre cada flag, consulte a referência do comando update.

Configuração no console do Google Cloud Sinalizações
Nome do app --display-name
URL do avatar --avatar-uri pelo URL HTTPS de uma imagem que atenda aos requisitos de avatar ou --clear-avatar-uri para usar o avatar padrão.
Descrição --description
Status do app --state=active ou --state=disabled
Sintaxe de marcação --markup-syntax=markdown ou --markup-syntax=chat
Participar de espaços e conversas em grupo --supports-multiuser-spaces ou --no-supports-multiuser-spaces
Configurações de conexão Opções:
  • URL do endpoint HTTP: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic com um tópico no mesmo projeto na nuvem, no formato projects/PROJECT_ID/topics/TOPIC_ID
  • Dialogflow: --dialogflow-edition=es ou --dialogflow-edition=cx com --dialogflow-agent definido como o nome do recurso do agente ou ambiente, como projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID
Visibilidade --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals e --clear-allowlisted-testing-principals
Registrar erros no Logging --error-logging-enabled ou --no-error-logging-enabled

Os comandos, as prévias de links e os endpoints separados para cada gatilho não têm sinalizações. Para configurá-los, use um arquivo de configuração.

Por exemplo, para desativar o app do Chat sem mudar as outras configurações, execute o comando a seguir. Para ativá-lo novamente, use --state=active.

gcloud beta workspace-add-ons chat-app-config update --state=disabled

Usar um arquivo de configuração

Para manter a configuração em um arquivo ou definir configurações que não têm flags, transmita um arquivo YAML ou JSON para o comando update. O arquivo usa os campos do recurso chatAppConfig, que são os mesmos campos que o comando describe imprime.

  1. Crie um arquivo com as configurações que serão atualizadas. Por exemplo, crie um arquivo chamado chat_app_config.yaml com o seguinte conteúdo:

    displayName: Cymbal Assistant
    description: Helps manage tasks and schedules
    avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
    state: ACTIVE
    errorLoggingEnabled: true
    interactiveFeatureConfig:
      supportsMultiuserSpaces: true
      connectionConfig:
        httpEndpointConfig:
          commonUrl: https://example.com/chat
      appCommands:
      - commandId: 1
        commandType: SLASH_COMMAND
        command: /help
        description: Show available commands
      urlPatterns:
      - hostPattern: example.com
        pathPrefix: tasks/
      allowlistedTestingPrincipals:
      - USER_EMAIL
    

    Substitua USER_EMAIL pelo endereço de e-mail de uma pessoa ou um grupo na sua organização do Google Workspace que possa instalar e testar o app do Chat.

  2. Execute o comando update com a flag --config-file:

    gcloud beta workspace-add-ons chat-app-config update \
        --config-file=chat_app_config.yaml

Para começar com a configuração atual de um app do Chat, salve a saída do comando describe em um arquivo:

gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yaml

Em seguida, edite o arquivo, exclua os campos que você não quer alterar e transmita o arquivo para o comando update. Se o arquivo tiver uma configuração que o comando não pode atualizar, ele vai falhar. Para mais detalhes, consulte Limitações.

O comando update ignora o campo name no arquivo. Ele sempre atualiza o projeto na nuvem definido na CLI gcloud. Assim, você pode usar o mesmo arquivo para configurar um app do Chat em outro projeto na nuvem.

Como o comando aplica as mudanças

  • Somente as configurações especificadas são alteradas. Com as flags, o comando muda as configurações das flags que você transmite. Com um arquivo de configuração, ele altera os campos que estão no arquivo, para que o arquivo não precise conter toda a configuração. As configurações de conexão são uma exceção: um tipo de conexão definido substitui o atual, e uma edição do Dialogflow definida substitui toda a configuração do Dialogflow.
  • As listas são substituídas como um todo. Se o arquivo tiver o campo appCommands, urlPatterns ou allowlistedTestingPrincipals, a lista no arquivo vai substituir a lista atual. Para adicionar ou remover testadores individuais, use as flags --add-allowlisted-testing-principals e --remove-allowlisted-testing-principals.
  • Um valor vazio limpa uma configuração. Por exemplo, um arquivo que contém urlPatterns: [] em interactiveFeatureConfig remove todos os padrões do URL de prévia de link.
  • Um comando que falha não muda nada. Se um valor não for válido, o comando vai mostrar o erro e deixar a configuração como estava.
  • As solicitações têm limitação de taxa. A API limita o número de solicitações de leitura e de atualização por minuto para cada projeto do Cloud e para cada organização. Cada comando update envia uma solicitação de atualização. Se você adicionar ou remover testadores com flags, o comando também vai enviar uma solicitação de leitura. Para mudar várias configurações, transmita-as em um comando ou arquivo, em vez de executar um comando para cada configuração.

Limitações

  • Os comandos só são compatíveis com apps do Chat criados como complementos do Google Workspace.
  • Os comandos não são compatíveis com contas de serviço ou identidade temporária de conta de serviço. É preciso fazer login na CLI gcloud com uma conta de usuário.
  • Um projeto na nuvem tem uma configuração de app do Chat, e os comandos não podem excluí-la. Para impedir que as pessoas usem o app do Chat, defina o estado como desativado ou exclua o projeto na nuvem.
  • Uma atualização se aplica ao app Chat ativo. Os comandos não têm um modo de rascunho ou de simulação.
  • Enquanto um app do Chat estiver publicado ou em análise no Google Workspace Marketplace, os comandos não poderão mudar o nome de exibição, o avatar, a descrição, os comandos ou os padrões de URL de visualização de link.
  • Os comandos são compatíveis com as configurações no recurso chatAppConfig. Para definir uma configuração que o recurso não inclui, use o console do Google Cloud.

Resolver problemas

Se um comando falhar, encontre o texto da mensagem de erro na tabela a seguir. Se a mensagem começar com um status como INVALID_ARGUMENT, a API Google Workspace Add-ons rejeitou a solicitação, e o texto após o status descreve o problema.

A mensagem de erro contém Causa Solução
Invalid choice: 'chat-app-config' ou Invalid choice: 'workspace-add-ons' O comando não inclui beta ou sua versão da CLI gcloud não inclui os comandos. Inicie o comando com gcloud beta workspace-add-ons chat-app-config. Se o erro persistir, atualize a CLI gcloud para a versão mais recente.
PROJECT ID O projeto está definido como um número de projeto. Defina o projeto como o ID do projeto.
Failed to parse value(s) in protobuf O arquivo de configuração contém um campo que a CLI gcloud não reconhece. A mensagem de erro nomeia o campo. Compare o nome do campo com a saída do comando describe. Se o campo for novo, atualize a CLI gcloud para a versão mais recente.
does not have permission to access projects instance A API negou a solicitação. O texto após essa mensagem informa o motivo. Exemplo:
  • Sua conta não tem os papéis do IAM necessários. Se o texto contiver Caller does not have required permission to use project, o papel de consumidor do Service Usage está ausente.
  • A API de complementos do Google Workspace não está ativada no projeto na nuvem.
  • Você fez login com uma conta de serviço.
Verifique os requisitos em Antes de começar.
INVALID_ARGUMENT Um valor não é válido. Por exemplo, o nome de exibição precisa ter entre 3 e 25 caracteres, e a descrição entre 1 e 40 caracteres. Se a mensagem contiver not found or deleted, o ID do projeto não está correto. Corrija o valor descrito na mensagem de erro e execute o comando novamente.
FAILED_PRECONDITION O app do Chat não permite a solicitação. Por exemplo, ele não foi criado como um complemento do Google Workspace ou foi publicado no Google Workspace Marketplace, e a configuração não pode ser alterada. Siga as instruções na mensagem de erro. Para configurar um app do Chat que não seja um complemento do Google Workspace, use o console do Google Cloud ou converta-o.
RESOURCE_EXHAUSTED ou 429 A API recebeu muitas solicitações para o projeto na nuvem ou para sua organização em um curto período. Aguarde um minuto e execute o comando novamente.

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, é possível 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 do primeiro salvamento. 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. Ative a API Google Workspace Add-ons (gsuiteaddons.googleapis.com) no 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.
  2. 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.
  3. 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, chat.bots.update e chat.bots.get para atualizar a configuração (UpdateChatAppConfig).
  4. Se você usa uma biblioteca de cliente, instale a versão mais recente da biblioteca de cliente da API Google Workspace Add-ons para sua linguagem. Para uma lista de bibliotecas de cliente, consulte a referência da API de complementos do Google Workspace.

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 visualização 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.

HTTP

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

Node.js

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

Python

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)

Limites de uso

Os métodos chatAppConfig têm cotas por projeto. Se você exceder uma cota, a solicitação vai falhar com um código de status HTTP 429: Too many requests. Para ver os limites de cota, consulte Limites de uso da API de complementos do Google Workspace.

Solucionar erros

Se uma solicitação chatAppConfig falhar, verifique o código de status HTTP e o campo message na resposta de erro. A tabela a seguir lista erros comuns, as causas deles e como resolvê-los.

Código de status HTTP Causas comuns Resolução
400: Bad Request (INVALID_ARGUMENT)
  • O updateMask contém um campo que não existe ou não pode ser atualizado.
  • Um valor de campo está ausente ou é inválido. Por exemplo, interactiveFeatureConfig não inclui um connectionConfig.
Verifique o campo message para encontrar o campo inválido e corrija a solicitação. Para ver os campos e valores compatíveis, consulte a referência de projects.chatAppConfig.
400: Bad Request (FAILED_PRECONDITION)
  • O app do Chat não foi criado como um complemento do Google Workspace.
  • Não é possível mudar o campo porque o app do Chat está publicado no Google Workspace Marketplace.
  • O novo valor não é compatível com a configuração atual do app do Chat.
  • Converta o app do Chat em um complemento do Google Workspace ou configure-o no console do Google Cloud.
  • Siga as instruções no campo message para atualizar a ficha publicada.
  • Verifique o campo message para encontrar a configuração conflitante e atualize as duas configurações na mesma solicitação ou mude a configuração atual primeiro.
403: Forbidden (PERMISSION_DENIED)
  • O usuário autenticado não tem as permissões do IAM necessárias no projeto na nuvem.
  • A solicitação é autenticada com uma conta de serviço em vez de uma conta de usuário.
  • Conceda ao usuário as permissões listadas em Pré-requisitos e autenticação.
  • Autentique-se como um usuário humano com o escopo https://www.googleapis.com/auth/cloud-platform.
404: Not Found (NOT_FOUND) O projeto na nuvem no nome do recurso não existe ou o usuário autenticado não pode acessá-lo. Verifique se o nome do recurso usa o número correto do projeto no formato projects/PROJECT_NUMBER/chatAppConfig e se o usuário tem acesso ao projeto na nuvem.
429: Too Many Requests (RESOURCE_EXHAUSTED) A cota por projeto foi excedida. Aguarde e tente fazer a solicitação mais tarde. Para limites, consulte Limites de uso.

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 atuais. Para atualizar sua listagem do Marketplace, crie um rascunho antes de enviar as mudanças.
  • Se você criou o complemento usando o Apps Script:
  • 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, com a CLI gcloud ou usando 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 navegar até 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.

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 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, Comandos iniciais, Visualizações de link, 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.