Watson Assistant
Uma vez que temos cadastrados todos os nossos Webhooks no Serprobots, podemos partir para utiliza-los no Watson Assistant! Veremos nesta seção como fazer uma chamada a um Webhook a partir de um diálogo dentro de uma Skill. Esta tarefa é simples mas, antes, você sabia que o Watson Assistant já tem suporte nativo a Webhooks?
Dica
Ainda não cadastrou seus Webhooks? Então, veja como cadastra-los na página de Configuração no Serprobots.
Webhook Nativo
Caso você já tenha utilizado o Watson Assistant, deve ter notado que ele provê uma funcionalidade de Webhooks. Contudo, o Serprobots não adota esta alternativa provida pela plataforma e também não a indica para os sistemas do Serpro. Vamos explicar os motivos!
Primeiro, veja como é o cadastro de um Webhook no Watson Assistant na Figura 1, que está logo abaixo. Note que é bastante similar ao cadastro de um Webhook no Serprobots, não acha? Então, quer dizer que funcionam da mesma forma? Na verdade, não.
Então, em que os Webhooks no Serprobots diferem dos Webhooks no Watson? Basicamente, para que o Watson Assistant possa chamar sua API, provavelmente hospedada dentro do Serpro, será necessário que seu sistema esteja aberto para ser acessado pela Internet.
Isto, obviamente, traz implicações de segurança, uma vez que será necessário prover mecanismos que evitem ataques como DDoS e outros. Há também os casos nos quais o sistema simplesmente não pode ser aberto na Internet mas, mesmo assim, precisamos obter informações desse sistema.
Então, como fazemos? O Serprobots adota uma alternativa mais segura e que explicaremos a seguir.
Webhook no Serprobots
Então, se o Serprobots não usa o recurso nativo do Watson Assistant para Webhooks, como ele faz para orientar o Watson a chamar os Webhooks que cadastramos anteriormente? Para isso, adotamos um modelo que é mais seguro, embora tenha necessidade de seguir alguns passos extras.
Na realidade, o processo é simples, pois o Watson permite que toda resposta dada por seu chatbot leve junto uma informação extra: uma ação a ser executada. Falando de forma mais prática, você terá que criar um diálogo que retorna uma ação que deve ser executada, ao invés de simplesmente uma resposta textual.
Como isso é mais seguro? É simples. Seu sistema não precisa estar disponibilizado na Internet. O fluxo é o seguinte: o Serprobots se comunica com a API do Watson e recebe uma solicitação de execução de uma ação. Então, o próprio Serprobots se comunica com sua API, internamente, e retorna a resposta da sua API para o Watson.
Para saber mais sobre as ações no Watson Assistant, acesse a página de documentação específica para esse assunto, mas, não se preocupe, pois vamos te mostrar como configurar uma ação!
Definindo Ações no Watson Assistant
Para criar uma ação, acesse sua instância do Watson Assistant e navegue até o Assistente no qual deseja adicionar a ação. Dentro do seu assistente, acesse a opção de Diálogos. Dentro desta tela, crie um diálogo com qualquer nome. No exemplo da Figura 2, criamos um diálogo com o nome Webhook.
Dica
Caso a interface do Watson Assistant esteja em inglês para você, então esta opção será apenas Dialog.
Logo em seguida, defina qual a Intent que irá acionar esse diálogo. Em nosso exemplo, criamos uma Intent simples (Figura 3), com o nome #webhook, e que tem apenas um exemplo, contendo o texto chamar webhook. Ou seja, toda vez que o usuário mandar uma mensagem apenas com o texto chamar webhook, esse diálogo será acionado.
Ainda na Figura 2, na seção Assistant Responds, defina uma resposta textual que o seu chatbot deve dar quando esse diálogo for acionado. Para nosso exemplo, vamos colocar apenas Aguarde, estamos consultando seus dados!.
Agora, logo ao lado do texto Assistant Responds, note que temos três pontinhos. Clique nesses três pontinhos e selecione a opção Open JSON editor. Note que agora temos um campo de texto com um código em JSON. Isso mesmo, toda resposta do Watson é um JSON e nós podemos editar esse JSON diretamente.
No nosso caso, vamos alterar este JSON para que ele inclua mais uma seção, que informará que uma ação deve ser executada pelo Serprobots.
{
"output": {
"generic": [
{
"values": [
{
"text": "Aguarde, estamos consultando seus dados!"
}
],
"response_type": "text",
"selection_policy": "sequential"
}
]
},
"actions": [
{
"name": "obterDadosCPF",
"type": "client",
"parameters": {
"cpf": "11111111111"
},
"result_variable": "action_result"
}
],
"context": {
"serprobots_skip_user_input": true
}
}
Vamos analisar o trecho de código acima? Focaremos mais no atributo chamado actions. Observe que podemos definir, nesse atributo, uma lista (Array) de ações. Para nosso exemplo, criamos apenas uma ação, cujo nome é obterDadosCPF. Neste ponto, precisamos prestar bastante atenção! O nome que você deve dar para a action é o mesmo nome que você definiu para o seu webhook dentro do Serprobots! Então, observe bem o nome para que não o tenha escrito de forma errada!
Seguindo, temos outro detalhe importante: o atributo type deve ser sempre client. Nunca use outro valor, apenas client. Após esse atributo, temos uma lista de parâmetros que serão passados para o Webhook. Note que definimos apenas um parâmetro, chamado cpf. Lembre-se: este parâmetro chegará na nossa API dentro de um Map, conforme vimos na seção sobre a Definição de uma API.
Finalizando, precisamos definir em qual variável de contexto do Watson Assistant o retorno do Webhook será armazenado. Neste caso, vamos armazenar na variável action_result. Observe que essa variável pode ser usada para compor uma resposta para o usuário, conforme veremos mais adiante. Vamos sumarizar essas informações na tabela abaixo!
| Atributo | Descrição |
|---|---|
| name | Define o nome da ação. Este nome deve ser IGUAL ao nome do Webhook no Serprobots |
| type | Define o tipo da ação e deve ser SEMPRE client. |
| parameters | Lista todos os parâmetros que devem ser passados para o Webhook |
| result_variable | Variável de contexto do Watson Context que conterá o valor de retorno do Webhook |
Aguardar o Usuário?
Ainda analisando o trecho de código da seção anterior, você notou o atributo chamado context? Este atributo contém as variáveis de contexto do Watson Assistant que podem ser enviadas para o Serprobots. Entretanto, nem todas as variáveis que são colocadas dentro do contexto são importantes para o funcionamento do Serprobots, exceto algumas como a serprobots_skip_user_input.
"context": {
"serprobots_skip_user_input": true
}
Por que esse atributo é importante? Porque ele define como o chatbot deve se comportar ao receber um pedido de execução de uma ação. Caso você defina esse atributo para conter o valor true, a interface de usuário (UI) padrão do Serprobots não aguardará que o usuário interaja com o chatbot para só então executar a ação. Descrevendo esse comportamento de forma prática, isso significa que a mensagem Aguarde, estamos consultando seus dados! será exibida para o usuário e o campo de entrada de texto será bloqueado até que seu Webhook seja executado e tenha dado uma resposta para o Watson Assistant.
Atenção: sugerimos que esta variável esteja sempre com o valor true, pois o comportamento descrito acima é o mais indicado para os chatbots.
Tratando o Retorno do Webhook no Watson Assistant
Agora que temos um diálogo que define uma chamada para um de nossos Webhooks, fica a pergunta: como podemos usar a resposta do Webhook para compor uma resposta para o usuário? É isso o que veremos a partir de agora!
Vamos voltar para o Watson Assistant e criar um nó-filho (child node) dentro do diálogo que já criamos, conforme a figura abaixo.
Contudo, antes de configurarmos este novo diálogo-filho, precisamos fazer uma mudança no diálogo-pai. Observe, na figura logo abaixo, que temos uma seção Then assistant should. Nesta seção, temos uma caixa de seleção, certo? Mude o valor de Wait for reply para Skip user input.
Dessa forma, você terá Skip user input and evaluate child nodes. Esta mudança informa ao Watson para que ele navegue imediatamente para o nó-filho assim que receber uma mensagem, neste caso, uma resposta da ação que pedimos para que fosse executada no diálogo-pai.
Agora, vamos configurar o nosso novo diálogo-filho? Vamos começar analisando a Figura 4 logo abaixo. Note que nomeamos o diálogo para Exibir Dados do CPF e, em seguida, usamos uma expressão no campo If assistant recognizes: $action_result.status != "ERROR". Que expressão é essa?
Para entendê-la, precisamos lembrar o que discutimos na seção Criando uma API, na qual avisamos que caso haja um erro na chamada ao Webhook, o Serprobots retornará como resposta um JSON contendo apenas um atributo chamado status e que este atributo terá o valor ERROR. Ou seja, esta expressão verifica se o retorno da API não foi um erro. Caso não tenha sido um erro, esse diálogo será selecionado!
Logo em seguida, já na seção Assistant responds, definimos apenas uma resposta textual simples, mas que está usando a nossa variável de retorno do Webhook! Veja que a resposta é composto por um texto puro, junto com a expressão $action_result.name. Lembre-se que action_result é a variável de contexto do Watson que guardará o retorno do Webhook e que esse retorno é um JSON, portanto, estamos acessando o atributo name deste JSON retornado pela nossa API.
Como tratamos erros?
Explicamos acima o caminho feliz, quando nenhum erro no processamento foi detectado. Entretanto, erros podem acontecer e precisamos estar preparados para quando isso ocorrer. Para tratarmos um erro na chamada ao Webhook, vamos criar um novo diálogo-filho, igual ao da Figura 5.
Nomearemos este diálogo como Tratando Erro na Chamada e usaremos a expressão $action_result.status == "ERROR" em If assistant recognizes. Na seção Assistant responds, daremos uma resposta textual simples: Não conseguimos processar sua requisição agora. Tente novamente..
Simples, certo? Observe que precisamos apenas trocar a expressão para $action_result.status == "ERROR" e agora esse diálogo será selecionado caso haja algum erro no processamento!
Pronto! Seu Webhook está pronto e funcionando!
Como tratar códigos de status HTTP
Caso seja necessário, você também pode tratar o código de status do HTTP retornado pela chamada que o webhook fez à sua API. O código do status será retornado para o Watson através da variável $action_result.sb_webhook_status_code. Este código pode ser usado nas condições de entrada de um diálogo, por exemplo.