Conectar um app do Chat a outros serviços e ferramentas

Nesta página, descrevemos como conectar um app do Google Chat a um serviço ou ferramenta fora do Google Chat. Embora os apps de chat sejam poderosos por si só, eles geralmente funcionam em conjunto com outros sistemas e exigem aplicativos complementares para conectar contas, autorizar o acesso a dados, mostrar informações adicionais ou configurar preferências do usuário.

Para autenticar usuários com um serviço de terceiros ou fluxo OAuth, seu app do Chat realiza as seguintes etapas:

1. Detectar quando a autorização ou configuração é necessária.
2. Retorne um card de autorização básica que solicite ao usuário fazer login ou configurar o serviço.
3. Redirecione para o URI de conclusão para que o Google Chat tente novamente a interação original automaticamente depois que o usuário concluir a autorização.

Pré-requisitos

Detectar que a autorização é necessária

Ao interagir com seu app do Chat, os usuários podem não ter autorização para acessar um recurso protegido por vários motivos, como os seguintes:

• Um token de acesso para se conectar ao serviço de terceiros ainda não foi gerado ou expirou.
• O token de acesso não abrange o recurso solicitado.
• O token de acesso não abrange os escopos necessários da solicitação.

Seu app do Chat precisa detectar esses casos para que os usuários possam fazer login e autorizar o acesso ao seu serviço.

Se você estiver criando no Google Apps Script, use a biblioteca OAuth2 para Google Apps Script (ou a versão OAuth1), em que a função hasAccess verifica se o usuário autorizou o acesso a um serviço. Como alternativa, ao usar solicitações UrlFetchApp.fetch, é possível definir o parâmetro muteHttpExceptions como true para inspecionar o código de resposta e o conteúdo no objeto HttpResponse retornado.

Solicitar aos usuários um card de autorização básica

Quando o app do Chat detectar que é necessária autorização ou configuração, retorne uma resposta AuthorizationError para mostrar um card de autorização básica particular ao usuário.

A imagem a seguir mostra um exemplo do cartão de autorização básica do Google:

Para mostrar aos usuários um card de autorização básica, retorne um objeto AuthorizationError:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Substitua:

• AUTHORIZATION_URL: o URL HTTPS do web app que processa autenticação, autorização ou configuração.
• RESOURCE_DISPLAY_NAME: o nome de exibição do recurso ou serviço protegido. Esse nome é mostrado ao usuário na solicitação de autorização. Por exemplo, se o RESOURCE_DISPLAY_NAME for Example Account, a solicitação vai dizer que o app precisa de aprovação para acessar seu Example Account.

Concluir a solicitação de configuração

No Chat, o usuário pode concluir o processo de autorização e fazer com que o Chat tente novamente a interação original automaticamente sem uma atualização manual. O Chat oferece suporte à nova tentativa automática se o gatilho for Mensagem, Adicionado ao espaço ou Comando do app.

Para esses gatilhos, seu app do Chat recebe um URI de redirecionamento de conclusão (configCompleteRedirectUri / completeRedirectUri) no payload do evento:

• Mensagem: chat.messagePayload.configCompleteRedirectUri
• Adicionado ao espaço: chat.addedToSpacePayload.configCompleteRedirectUri
• Comando do app: chat.appCommandPayload.configCompleteRedirectUri

Você precisa codificar esse URI de redirecionamento no seu <var>AUTHORIZATION_URL</var> e redirecionar o navegador do usuário para ele após a conclusão do fluxo de autorização. O redirecionamento para esse URL indica ao Google Chat que a solicitação de autorização ou configuração foi atendida.

Quando um usuário é redirecionado para o URI de redirecionamento de conclusão fornecido no payload do evento original, o Google Chat realiza as seguintes etapas:

1. Apaga a solicitação de autorização particular mostrada ao usuário que iniciou a ação.
2. Converte a mensagem original em pública, tornando-a visível para outros membros do espaço.
3. Envia o objeto de evento original para seu app do Chat uma segunda vez.

Se você não redirecionar para o URI de redirecionamento de conclusão, o usuário ainda poderá concluir o fluxo de autorização, mas o Google Chat não vai tentar novamente a execução anterior de forma automática, e o usuário precisará invocar seu app do Chat manualmente outra vez.

Visitar um URI de redirecionamento de conclusão afeta apenas uma interação do usuário. Se um usuário tiver enviado mensagens para um app de chat várias vezes e recebido várias solicitações, concluir o processo de autenticação e configuração para uma solicitação vai repetir apenas essa interação específica.

Autenticar o usuário do Chat fora do Chat

Ao vincular a um URL fora do Chat (como um callback da Web OAuth), geralmente é necessário correlacionar a sessão da Web externa com a identidade do usuário no Chat. Recomendamos que você proteja o web app de destino com o Login do Google.

Use o token de identidade emitido durante o login para receber o ID do usuário. A declaração sub contém o ID exclusivo do Google do usuário e pode ser correlacionada com o nome do recurso do usuário (chat.user.name) do Google Chat.

Para correlacionar a declaração sub com um nome de recurso users/{user} do Google Chat, adicione o prefixo users/ ao valor da declaração sub. Por exemplo, um valor de declaração sub de 123 corresponde a users/123 em objetos de evento enviados ao seu app de chat.

Amostras de código

Os exemplos de código a seguir demonstram como um app de chat pode solicitar credenciais OAuth2 off-line usando um card de autorização básico, armazenar em um banco de dados, redirecionar para o URI de conclusão e fazer chamadas de API com autenticação do usuário:

Temas relacionados

• Receber e responder a interações do usuário
• Autenticar e autorizar apps do Google Chat e solicitações de API do Google Chat
• Conectar o complemento do Google Workspace a um serviço de terceiros

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}