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

Embora os apps sejam poderosos por si só, eles geralmente funcionam em conjunto com outros sistemas e exigem aplicativos complementares para conectar contas, autorizar acesso a dados, exibir dados adicionais ou configurar preferências do usuário.

Solicitar configuração do app

Além de apresentar URLs como parte de uma resposta normal, os apps podem apresentar de maneira particular um URL de configuração para o usuário em resposta a uma mensagem.

Retornar um URL de configuração

Se a conclusão de uma solicitação exigir outras configurações que não podem ser concluídas diretamente no app, retorne uma resposta do seguinte formulário:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

Isso instrui o Google Chat a apresentar ao usuário um prompt particular, com um link para acessar o URL de configuração fornecido para autenticação, autorização ou configuração. As respostas de solicitação de configuração são mutuamente exclusivas com uma mensagem de resposta normal. Textos, cards ou outros atributos são ignorados.

Cada evento do app também inclui um parâmetro configCompleteRedirectUrl. Esse URL precisa ser codificado no URL de configuração para ser usado após a 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 for iniciado, o fluxo poderá depender da mensagem específica recebida. Em resposta a uma mensagem como @app help, um app precisa responder com uma mensagem sem exigir mais configuração.

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

1. Apagar a solicitação exibida para o usuário inicial
2. Converter a mensagem original em pública, tornando-a visível para os outros participantes do espaço
3. Envio da mensagem original para o mesmo app uma segunda vez

Visitar um configCompleteRedirectUrl afeta apenas uma mensagem do usuário. Se um usuário tentou enviar uma mensagem para um app várias vezes e, como resultado, recebeu várias solicitações, clicar em uma solicitação específica e concluir o processo de autenticação/configuração afeta apenas essa mensagem ou solicitação específica. As outras mensagens e solicitações não serão alteradas.

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

Identificar o usuário nas mensagens do app

Cada mensagem enviada para o app inclui a identidade do usuário que interage com ele.

O exemplo de fragmento JSON abaixo mostra o formato esperado da identidade do usuário em uma mensagem para o app.

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

Use o valor da propriedade users.name como o ID principal do usuário. O valor é um ID estável e exclusivo para cada usuário.

Identificar o usuário do Chat fora do Google Chat

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

Embora os dois IDs não sejam exatamente idênticos, eles são facilmente convertidos. Para coagir o valor da declaração sub a um nome de usuário do Google Chat, inclua "users/" antes do valor. Por exemplo, o valor da reivindicação 123 é equivalente ao nome de usuário users/123 nas mensagens para seu app de Chat.

Exemplo completo

O app MyProfile demonstra como usar a resposta REQUEST_CONFIG para iniciar a configuração do app e usa o token de identidade da resposta do Login do Google para identificar o usuário.