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

Esta página descreve como conectar um app do Google Chat a um serviço ou ferramenta fora do Google Chat. Embora os apps do Chat sejam poderosos por conta própria, eles geralmente funcionam em conjunto com outros sistemas e exigem aplicativos complementares para conectar contas, autorizar o acesso aos dados, mostrar dados adicionais ou configurar preferências do usuário.

Pré-requisitos

Um app do Google Chat configurado para receber e responder a eventos de interação. Para criar um um app interativo do Chat, conclua um dos seguintes guias de início rápido com base na arquitetura do app que você quer usar:

Solicitar a configuração do app do Chat a um usuário

Se a conclusão de uma solicitação exigir uma configuração adicional que não possa ser concluída diretamente no app do Chat, retorne um URL de configuração ao usuário como parte de uma resposta normal ou apresente-o de forma particular, no seguinte formato:

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

Isso informa ao Google Chat para apresentar ao usuário um comando particular, em que CONFIGURATION_URL é um link para o usuário acessar para autenticação, autorização ou configuração adicional. Uma resposta REQUEST_CONFIG é mutuamente exclusiva com uma mensagem de resposta normal. Qualquer texto, card ou outros atributos são ignorados.

Concluir a solicitação de configuração

Cada evento de interação MESSAGE, ADDED_TO_SPACE, e APP_COMMAND que o app do Chat recebe também inclui o campo configCompleteRedirectUrl. É necessário codificar esse URL no URL de configuração para ser usado na conclusão do processo. O redirecionamento para esse URL indica ao Google Chat que a solicitação de configuração foi atendida.

Quando o app do Chat é iniciado, o fluxo depende da mensagem específica recebida. Em resposta a uma mensagem como @app help, um app do Chat precisa responder com uma mensagem sem exigir configuração adicional.

Quando um usuário é redirecionado para o configCompleteRedirectUrl fornecido na mensagem original, o Google Chat realiza as seguintes etapas:

  1. Apagar o comando mostrado ao usuário iniciador.
  2. Converter a mensagem original em pública, tornando-a visível para outros membros do espaço.
  3. Enviar a mensagem original para o mesmo app do Chat uma segunda vez.

Acessar um configCompleteRedirectUrl afeta apenas uma única mensagem do usuário. Se um usuário tentou enviar mensagens para um app do Chat várias vezes e, como resultado, recebeu vários comandos, clicar em um comando específico e concluir o processo de autenticação e configuração afeta apenas essa mensagem específica. Outras mensagens não são alteradas.

Quando um evento de interação MESSAGE é reenviado dessa forma, ele precisa ser idêntico ao evento original. No entanto, há algumas situações em que os eventos de interação MESSAGE podem ser diferentes. Por exemplo, quando uma mensagem menciona o app A e o app B do Chat, o usuário pode editar a mensagem se o app A responder com uma mensagem normal antes de se autenticar com o app B. Nesse caso, o app B do Chat recebe o texto da mensagem editada depois que o usuário conclui a autenticação e a configuração.

Autenticar o usuário do Chat fora do Chat

Em alguns casos, como solicitar a autorização do OAuth para uma API, o app precisa se vincular a um URL fora do Chat, mantendo a identidade do usuário. A melhor maneira de identificar o usuário nesses casos é proteger o app de destino com 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 usuário e pode ser correlacionada com o ID do usuário do Google Chat.

Embora os dois IDs não sejam exatamente idênticos, eles podem ser forçados. Para forçar o valor da declaração sub a um users/{user} do Google Chat, adicione o valor com users/. Por exemplo, o valor da declaração 123 é equivalente ao nome de usuário users/123 em mensagens para o app do Chat.