Sessão Autenticada

Uma sessão autenticada garante que o Gateway do Serprobots saiba quem o está requisitando, garantindo que o seu Entreposto ganhe algumas funcionalidades extras:

• Passar parâmetros que podem ser lidos e utilizados pelos motores de IA (IBM Watson);
• Passar um token de usuário que pode ser utilizado nas chamadas aos Webhooks.

Entretanto, quando essas duas funcionalidades são úteis? Quando as utilizarei em meu chatbot? Por exemplo, suponha que seja necessário exibir na conversação o nome do usuário ou outros dados sensíveis (claro, estamos supondo que seu entreposto tenha primeiro autenticado este usuário), enviados diretamente pelo seu Entreposto para o motor de IA. Como faço? Sem sessão autenticada, isto não é possível! Aliás, esta é uma boa prática e dá uma caráter mais pessoal à conversação.

E quanto ao token nas chamadas do webhook? Neste caso, sua API, que contém os endpoints que são chamados pelos webhooks, pode requerer uma autenticação específica do usuário que está conversando com o chatbot. Por exemplo, a API é autenticada e precisa de um token de usuário para obter dados específicos sobre ele.

Está convencido de que essas duas funcionalidades são interessantes? Então, vamos ver agora como configurar uma sessão autenticada no Serprobots e como utilizar essas duas novas funcionalidades na prática.

Configurando os Tokens

A sessão autenticada é configurada de forma bastante fácil. Inicialmente, acesse o chatbot que deseja editar e, logo em seguida, clique na opção Sessão Autenticada que se encontra no menu esquerdo, conforme demonstra a figura abaixo.

Uma vez nesta tela, note que estão listados os dois ambientes nos quais seu chatbot pode ser publicado: Desenvolvimento e Produção. Logo à direita de cada ambiente, observe que temos duas ações disponíveis: Criar e Revogar. Para que essas opções servem? Servem para criar tokens que devem ser usados pelo Entreposto ao realizar uma chamada ao nosso Gateway!

Vamos lá! Clique no botão Criar que está associado ao ambiente de Desenvolvimento, conforme a imagem acima. Ao fazer isto, será criado um token específico para este ambiente e que será exibido em uma caixa logo acima, como você pode ver na imagem abaixo. Fique atento ao aviso: você deve copiar este token em um prazo de 60 segundos, pois esta caixa sumirá e nunca mais exibiremos este token de novo!

Note que a listagem agora também exibe outras informações. A primeira é a data de criação do token, enquanto a segunda é quando este token irá expirar. Colocamos um valor padrão bem alto para que você não precise se preocupar em renovar este token a todo momento.

Cabe aqui um alerta importante!. Uma vez que você cria um token para um determinado ambiente, o Gateway do Serprobots PERMITIRÁ SOMENTE CHAMADAS AUTENTICADAS. Ou seja, este token precisa estar incluído em todas as chamadas realizadas ao Gateway, pois, caso contrário, você receberá um erro do tipo 401 UNAUTHORIZED.

Fique atento

Você não precisa republicar o chatbot para que as configurações de sessão autenticada surtam efeito! Basta modificá-las que elas já estarão valendo no ambiente!

Por último, você pode revogar a qualquer momento um token ou criar um novo para substituir o atual. Para revogar, basta clicar no botão Revogar. Enquanto, para criar um novo, basta clicar de novo em Criar.

Requisitando o Gateway

Tudo bem, agora que eu tenho meu token, o que eu faço com isso? É simples! TODA chamada ao Gateway do Serprobots, a partir de agora, deve incluir o cabeçalho Authorization contendo o valor Bearer seutoken, onde seutoken é o token que você obteve na seção anterior. Sim, é só isso mesmo. A partir de agora, o Gateway não recusará mais as chamadas do seu Entreposto.

Passando Parâmetros

Legal! Já posso passar parâmetros para que o motor de IA utilize na conversação? Sim e é bastante simples fazer isso. Lembra que criamos a classe Message quando falamos sobre como criar seu Entreposto? Lembra também que você deve passar uma instância desta classe para o Gateway, certo? Então, vamos listar esta classe novamente logo abaixo, para facilitar:

data class Message(
  var conversationId: UUID? = null,
  var text: String? = null,
  var parameters: Map<String, Any?>? = emptyMap()
) 

Notou o atributo parameters? Este atributo será absolutamente ignorado pelo Serprobots quando você não estiver utilizando uma sessão autenticada, mas será permitido, caso contrário. Este atributo é um Map e você pode incluir pares de chave/valor que chegarão até o motor de IA e, a partir deste motor, você pode interpolar valores enviados pelo seu Entreposto com o texto que você enviará como resposta à pergunta de um usuário!

Webhooks

Temos uma seção inteira em nossa documentação que explica detalhadamente como configurar e utilizar webhooks, lembra? Você observou também que a forma como chamamos os webhooks não foi autenticada? Ou seja, nós não estávamos passando, por exemplo, um token JWT para que sua API validasse e soubesse quem é o usuário que está realizando a chamada!

Usando somente o conceito de webhooks, você pode passar um token fixo através dos cabeçalhos, conforme a imagem acima. Isto é útil somente quando sua API depende de um token fixo para validar a chamada, mas é de pouca importância quando você precisa que esse token seja dinâmico, representando uma autenticação realizada por um usuário do chatbot.

Para termos esse token do usuário sendo usado nos webhooks, precisamos de um Entreposto e de uma sessão autenticada. Por que precisamos do Entreposto? Porque fica a cargo do seu Entreposto autenticar o usuário. O Serprobots não realiza essa autenticação, pois isto é competência do seu sistema. O seu Entreposto deve apenas informar ao Gateway do Serprobots qual é o token do usuário que deve ser usado nas requisições aos webhooks!

Informando o Token

Para que o Gateway saiba que deve anexar um token em algum cabeçalho (discutiremos sobre isso em breve), você deve adicionar um parâmetro extra no atributo parameters da classe Message.

data class Message(
  var conversationId: UUID? = null,
  var text: String? = null,
  var parameters: Map<String, Any?>? = emptyMap()
) 

A chave deste parâmetro DEVE SER o valor X-SERPROBOTS-WEBHOOK-AUTH-TOKEN. Faça um COPY & PASTE neste valor para não errar! E o valor deste parâmetro? Obviamente, é o token do usuário que você quer que seja usado na requisição ao webhook!

Está faltando só um passo: informar em qual cabeçalho este valor chegará para a sua API. Isto é feito através do Gerenciador do Serprobots. Observe a imagem acima. Note que criamos que um cabeçalho chamado Authorization e que contém o valor Bearer {X-SERPROBOTS-WEBHOOK-AUTH-TOKEN}. Fácil de entender, certo? O Serprobots irá substituir a marcação {X-SERPROBOTS-WEBHOOK-AUTH-TOKEN} pelo valor do token que você informou ao Gateway.

Pronto! Temos tudo configurado e, a partir de agora, sua API sempre receberá um cabeçalho Authorization contendo Bearer acompanhado do token do usuário que seu Entreposto informar!

Autenticando seu Usuário

Lembra que dissemos que o processo de autenticação do usuário é responsabilidade do seu sistema? Neste caso, acreditamos que você pode ter ficado com uma dúvida simples: como eu uso um chatbot criado no Serprobots em uma área restrita do meu site? Vamos considerar um fluxo tradicional, no qual o usuário entra na página de autenticação e digita seu usuário e senha. Logo após isso, ele ganha acesso a uma área restrita.

Nesta área restrita, seu sistema provavelmente atribui alguma identificação a este usuário, como um token JWT, por exemplo. O cenário mais comum é que a interface do seu sistema inclua esse token JWT em todas as requisições através de algum cabeçalho. Em seu backend, você valida este token e permite ou não o acesso a uma determinada funcionalidade.

Você também vai incluir o seu chatbot criado no Serprobots nesta área restrita e, neste caso, aparecerá aquela janelinha característica do chatbot, onde o usuário pode clicar para começar a conversar com seu robô. Como você tem um Entreposto, todas as mensagens da conversa do chatbot serão intermediadas por esse Entreposto e não enviadas diretamente para o Gateway do Serprobots, correto?

Então, como você pede ao Serprobots para ele incluir o token JWT que identifica o usuário logado em cada mensagem enviada pelo usuário? Inicialmente, cabe lembrar que nossa UI é totalmente construída usando o framework Angular e também um pouco de Javascript Vanilla (Javascript puro). Portanto, se você tem um token para informar ao Serprobots, precisa fazê-lo através de código Javascript (Typescript também).

É simples fazer isso. Antes de enviar cada mensagem digitada pelo usuário ao seu Entreposto, nossa UI irá checar se existe um objeto em window.serprobots_http_headers. Caso exista, ele espera que este objeto seja um dicionário contendo chaves e valores que serão usados no cabeçalho da requisição. Neste caso, você pode fazer algo semelhante ao código abaixo:

window.serprobots_http_headers = { "Authorization": "Bearer " + variavelQueContemOToken };