Criando uma API

O primeiro passo a ser definido antes de partirmos para a criação de um webhook dentro do Serprobots é determinar a API que usaremos para obter algum dado que possamos usar para exibir ao usuário do chatbot. Neste caso, precisaremos criar uma API RESTful com um retorno em JSON.

Não importa, para o Serprobots, qual a linguagem e framework utilizados para criar essa API, entretanto, você precisa ficar atento a alguns detalhes durante a criação do método que receberá a chamada do Webhook.

Vamos apresentar aqui um exemplo em Kotlin, usando a JAX-RS, que é a especificação para a criação de serviços RESTful em Java/Kotlin. Não nos aprofundaremos nos detalhes da tecnologia em si, mas apresentaremos apenas os detalhes que você deve ter atenção.

package serprobots.controller

import javax.ws.rs.POST
import javax.ws.rs.Path
import javax.ws.rs.Produces
import javax.ws.rs.core.MediaType.APPLICATION_JSON

@Path("/cpf")
class CPFController {

    @POST
    @Produces(APPLICATION_JSON)
    fun obterCPF(body: Map<*, *>): CPFResult {
        return when(body["cpf"]) {
            "11111111111" -> CPFResult("João da Silva", "111.111.111-11")
            "22222222222" -> CPFResult("Maria das Graças", "222.222.222-22")
            else -> CPFResult("CPF não encontrado", body["cpf"])
        }
    }

    data class CPFResult(var name: String, var cpf: String)
}

O trecho de código acima exemplifica a criação de uma classe que funcionará como um Controller, no qual temos o uso da anotação Path() para definir um endpoint com o caminho /cpf. Assim, caso esta API seja publicada no endereço https://api.serpro.gov.br, teremos um endpoint apontando para o endereço https://api.serpro.gov.br/cpf.

Logo em seguida, temos a definição de um método que será o responsável por receber uma chamada usando o método POST (através da anotação @POST) e que produz uma resposta no formato JSON (através da anotação @Produces).

Dica

O Serprobots dá suporte apenas ao método POST. Futuramente, os métodos PUT e GET também serão disponibilizados.

O nome do método é irrelevante, mas o parâmetro que esse método deve receber é importante! Sempre use um único parâmetro, que deve ser do tipo Map. Este mapa conterá todos os parâmetros que o Webhook receberá do Watson Assistant ou do Rivescript.

Dica

O Serprobots sempre passará no corpo da chamada um Map contendo a lista de parâmetros. Futuramente, o Serprobots se tornará flexível o suficiente para que os parâmetros também sejam enviados de outras formas, como através do path ou querystring.

O retorno da API pode ser qualquer objeto, desde que este objeto seja serializado para JSON. Neste exemplo, estamos simulando uma consulta a uma base de dados de CPF que contém apenas dois CPFs: 111.111.111-11 e 222.222.222-22. Caso o CPF seja diferente de um desses dois, retornamos uma mensagem de CPF não encontrado.

Erros na Chamada à API

O que acontece quando o Webhook chama a API mas ocorre um erro? Esta informação será logada no Serprobots e todos os contatos cadastrados no Chatbot serão notificados deste erro. Outro detalhe importante: a variável de contexto na qual o resultado da chamada seria guardado conterá um único atributo: status. Esta variável conterá o valor ERROR.

Desta forma, é possível que você faça uma verificação se esta variável existe e se o valor é ERROR para definir qual diálogo será chamado no Watson Assistant.

Segurança

Gostaria que as chamadas ao seu webhook fossem autenticadas? Por exemplo, recebendo um token JWT do usuário que está interagindo com o chatbot através do cabeçalho Authorization? Isto só é possível através do uso de uma sessão autenticada. Para saber mais como utilizar sessões autenticadas, visite esta seção!