Parâmetros de request/response da conversa do Conversation

Este é o terceiro post sobre o serviço Watson Conversation. Nele irei explicar em detalhes os parâmetros do endpoint /message, pelo qual conseguimos enviar e receber as respostas do Conversation, e também algumas boas práticas para enviar/receber dados do Conversation.

Endpoint /message

O endpoint responsável pela troca de mensagens no Conversation é o:

POST /v1/workspaces/{workspace_id}/message

Parâmetros de request

Ao realizar uma chamada no endpoint /message, deve-se passar:

workspace_id

O parâmetro workspace_id é uma string, obrigatório, e deve ser passado no PATH e representa o workspace no qual a conversa será realizada.

version

O parâmetro version é uma string, obrigatório, deve ser passado na QUERY da chamada, e define a data da versão da API que será utilizada e deve ser enviado na query da chamada. A versão mais recente é a de 2017–02–03, e a anterior a ela é a de 2016–09–20. A principal diferença entre estas duas versões é que a mais recente retorna as confianças das intenções com score absoluto (cada intenção tem a sua confiança real), enquanto a anterior retornava esse score normalizado (a soma das confianças de todas as intenções é igual a 1). Essa mudança pode ter impacto na forma de utilizar as confianças. Entrarei em mais detalhes sobre isso em um post futuro.

input

O parâmetro input é um objeto JSON, opcional, e deve ser enviado no body da chamada. Ele contém uma propriedade chamada text, que é uma string, representando o texto que você quer enviar para o Conversation. No entanto, este objeto tem muitas outras utilidades, se usado da forma correta.

"input": {
"text": "",
"saldo": "1000"
}

alternate_intents

O parâmetro alternate_intents é um booleano, opcional, e deve ser enviado no body da chamada. Ele diz para o conversation se devem ser retornadas todas as intenções reconhecidas (no máximo 10 em ordem decrescente de confiança) ou apenas a intenção de maior confiança. Por padrão este parâmetro é false. Portanto, caso queira ter todas as intenções retornadas deve-se enviar true.

"alternate_intents": true

context

Como explicado no post anterior, o parâmetro context é um objeto JSON, opcional, e deve ser enviado no body da chamada. Ele representa o estado da conversa. Sem ele o conversation não saberia dizer se é uma conversa nova ou de qual nó ele deve continuar. Caso ele não seja enviado, o Conversation irá sempre interpretar como uma conversa nova, e poderá retornar sempre a mesma resposta, dependendo de como esteja configurado.

"context": {
"nome": "Franklin",
"sobrenome": "Guimarães"
"conversation_id": "66a91bd9-48f5-4d3d-8179-46b586814f1f",
"system": {
"dialog_stack": [
{
"dialog_node": "root"
}
],
"dialog_turn_counter": 1,
"dialog_request_counter": 1,
"_node_output_map": {
"Start And Initialize Context": [
0,
0
]
},
"branch_exited": true,
"branch_exited_reason": "completed"
}
}

entities

O parâmetro entities é um array, opcional, e deve ser enviado no body da chamada.

"entities": [
{
"entity": "appliance",
"location": [
12,
18
],
"value": "lights"
}
]

intents

O parâmetro intents é um array, opcional, e deve ser enviado no body da chamada.

"intents": [
{
"intent": "turn_on",
"confidence": 1
}
]

output

O parâmetro output é um objeto JSON, opcional, e deve ser enviado no body da chamada.

Parâmetros de response

input

É sempre retornado e possui o mesmo valor do input enviado no request.

alternate_intents

É retornado apenas se for enviado no request. Neste caso retornará com o mesmo valor.

context

É sempre retornado. O parâmetro context pode ser alterado dentro do conversation para salvar informações relevantes para o diálogo. Para isto é utilizada a linguagem SpEL. Eu cobrirei estas alterações com mais detalhes em um post futuro, porém caso queiram dar uma olhada podem entrar neste site. A propriedade conversation_id será sempre a mesma (pois representa o id da conversa) enquanto a propriedade system será atualizada pelo Conversation para corresponder ao novo estado da conversa.

entities

Sempre quando um input é enviado para o Conversation, ele tentará reconhecer quais das entidades cadastradas ocorrem no input, retornando elas sempre que encontradas.

intents

Sempre quando um input é enviado para o Conversation, ele tentará classificar o input do usuário nas intenções cadastradas, retornando no máximo 10 intenções em ordem decrescente de confiança.

output

Será sempre retornado como um objeto e que representa o retorno do fluxo de diálogo. Ele possui por padrão três propriedade: log_messages (array de string com mensagens de log. Útil para saber se há algum erro ou aviso no fluxo de diálogo), text (array de string com as mensagens retornadas pelo conversation, aquelas que serão mostradas ao usuário) e nodes_visited (array de string com os nome dos nós dos do diálogo visitados na chamada do Conversation. Útil para testar se o fluxo está correto). Porém, assim como o input, este objeto pode ser muito útil se utilizado corretamente.

"output": {
"log_messages": [],
"text": [
"O saldo da sua conta corrente é "
],
"nodes_visited": [
"consultar_saldo"
],
"codigo_operacao": "consultar_saldo_cc"
}

O que fazer em seguida

Para melhor compreender estes conceitos, sugiro praticar as chamadas ao Conversation utilizando o API Explorer (veja post anterior) e também ler as referências abaixo:

Posts relacionados

Introdução ao Serviço Watson Conversation

Senior Software Engineer @ LogMeIn

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store