Configuração avançada de chatbots

O Tolvnow permite que você crie chatbots através de Fluxos visuais ou através de estruturas de código JSON.

Neste artigo iremos apresentar o procedimento de configuração avançado através do código JSON.  

Atenção: se você não tem experiência com programação, em especial, estruturas JSON, este artigo pode não ser adequado.

Esta opção permite que sejam feitas exatamente as mesmas funções que a criação por fluxo conversacional, sendo que na maioria das situações, não há vantagens em utilizar este método, mesmo para os programadores mais experientes. Entretanto, em alguns cenários, você pode utilizar a edição de código para copiar e colar blocos de forma mais rápida do que seria feito no diagrama visual. Entretanto, tome cuidado com os parâmetros ID dos blocos, pois é muito fácil duplicá-los. 

Estrutura básica do código JSON:

{
   "flow-version": 1,  
   "name": "novo fluxo",
   "startId" : 1, 
   "blocks": [] 
}

• ​flow-version: versão do fluxo.
• name: nome do fluxo
• startId: código (id) do bloco inicial (o mesmo efeito do bloco start)
• blocks: lista (array) dos blocos do fluxo conversacional

Dentro da propriedade blocks você irá incluir os passos que o sistema de chatbot irá percorrer para responder aos usuários. O encadeamento dos passos será feito através do uso das propriedades id e next. 

Veja este exemplo:

{
  "flow-version": 1,
  "name": "novo fluxo",
  "startId": 1,
  "blocks": [
    {
      "id": 1,
      "type": "start",
      "next": 2
    },
    {
      "id": 2,
      "type": "text-message",
      "data": {
        "text": "Olá! Bem vindo ao chatbot!"
      },
      "next": 3
    },
    {
      "id": 3,
      "type": "end"
    }
  ]
}

No código acima, utilizamos 3 blocos: start, text-message, end. Observe que o primeiro bloco indica a propriedade next como 2, que é o id do segundo bloco. No segundo bloco a propriedade next é 3, que é o id do terceiro e último bloco. O chatbot com a configuração acima simplesmente iniciaria, enviaria uma mensagem "Olá! Bem vindo ao chatbot!" e encerraria. De forma simples, é assim que o fluxo através dos blocks funciona. 

Agora vamos avançar nos diferentes tipos de blocos que o Tolvnow permite utilizar até o momento. 

Bloco indicador de início:

Este bloco pode ser usado como alternativa à propriedade startId. Indica onde o processamento do fluxo irá iniciar. Havendo a propriedade startId definida na raiz do JSON, este bloco pode ser desconsiderado.

​{
  "id": 1,
  "type": "start",
  "next": 2
}

Bloco para enviar mensagem de texto:

Este bloco é utilizado para enviar mensagens de texto. 

{
  "id": 2,
  "type": "text-message",
  "data": {
    "text": "Olá! Bem vindo ao chatbot!"
  },
  "next": 22
}
​

Bloco para indicar espera (atraso):

Este bloco indica ao chatbot para esperar ou atrasar o fluxo em um determinado tempo em segundos. Este bloco é especialmente utilizado para tornar o fluxo de conversa mais humanizado e de fácil leitura. Por exemplo, se você for enviar diversas mensagens em sequencia, pode ser desagradável para o usuário ler todas elas na sequencia, desta forma, pode ser interessante incluir um pequeno atraso de alguns segundos. 

​
{
  "id": 28,
  "type": "delay",
  "data": {
    "time_seconds": 4
  },
  "next": 4
}

A propriedade data.time_seconds indica a quantidade de segundos que o chatbot irá esperar até seguir para a próxima etapa (text-message ou variable-request).

Bloco para captura de informações / perguntas

O chatbot deve efetuar perguntas para o usuário, como por exemplo, "Qual é o seu nome?". Para isso, utilizamos um bloco chamado variable-request. Como este bloco possui particularidades, vamos aprofundar um pouco mais. 

​{
  "id": 5,
  "type": "variable-request",
  "data": {
    "request": "Qual é o seu nome?",
    "data-type": "name",
    "set-as-name": true,
    "set-as-email": false,
    "set-as-identifier": true,
    "variable-name": "name",
    "success-message": "Ok, obrigado {{name}}!",
    "error-message": "Não entendi seu nome corretamente. Podes me informar novamente?"
  },
  "next": 6
}

Vamos falar agora sobre cada uma das propriedades dentro da propriedade data:

• ​request: é a pergunta que será exibida ao usuário, como se fosse uma mensagem.
• data-type: é o tipo de dado esperado da resposta. O Tolvnow só permitirá que o fluxo continue se a resposta do usuário estiver de acordo com o data-type. Os data-type's disponíveis neste momento são: name, email, cpf, cnpj, phone, text-options. Sobre o text-options, vamos falar um pouco mais adiante, os demais são auto-explicativos. 
• set-as-name: se definida como true (verdadeiro), o Tolvnow irá entender que este é o nome do usuário e irá definir a propriedade raiz nome do usuário com o valor desta variável.
• set-as-email: se definida como true (verdadeiro), o Tolvnow irá entender que este é o e-mail do usuário e irá definir a propriedade raiz email do usuário com o valor desta variável.
• set-as-identifier: se definida como true (verdadeiro), o Tolvnow irá entender que este é o e-mail do usuário e irá definir a propriedade raiz identificador do usuário com o valor desta variável.
  
• variable-name: este é o nome da variável à qual a resposta do usuário será salva e identificada. 
• success-message: mensagem que o chatbot irá informar ao usuário se a resposta for aceita / válida.
• error-message: mensagem que o chatbot irá informar ao usuário se a resposta for inválida.

Veja que na propriedade success-message há uma marcação {{name}}. Se a variável com o nome "name" estiver definida, o Tolvnow irá automaticamente substituir pelo seu valor. Você pode usar {{nome_da_variavel}} em qualquer mensagem de resposta ao usuário, no bloco atual ou em blocos futuros.

O bloco de perguntas ainda possui o recurso de mandar opções de resposta, na forma de um menu, onde o usuário pode clicar para responder. Isto é feito utilizando o data-type text-options. Veja o exemplo abaixo:

{
  "id": 22,
  "type": "variable-request",
  "next": 23,
  "data": {
    "request": "Gostaria de saber mais informações deste imóvel?",
    "data-type": "text-options",
    "variable-name": "ack",
    "success-message": "Ok, vamos adiante.",
    "error-message": "Escolha uma das opções.",
    "options": [
      "Sim",
      "Não"
    ]
  }
}

No exemplo acima, o chatbot irá exibir a pergunta "Gostaria de saber mais informações deste imóvel?" e logo abaixo duas opções de resposta "Sim" e "Não". A resposta do usuário será salva na variável ack, para que possa ser avaliada em um passo seguinte.

Bloco condicional de desvio de fluxo:

O bloco condicional de desvio de fluxo tem o objetivo de desviar o fluxo do chatbot de acordo com o valor de uma variável. Veja o exemplo abaixo:

​{
  "id": 23,
  "type": "if-variable-value",
  "data": {
    "variable": "ack",
    "conditions": [
      {
        "value": "Sim",
        "next": 4
      },
      {
        "value": "Não",
        "next": 24
      },
      {
        "value": "default",
        "next": 24
      }
    ]
  }
}

No exemplo acima, iremos verificar o valor da variável ack. Obviamente, esta variável já deve ter sido criada anteriormente. O Tolvnow irá utilizar as opções listadas em conditions para desviar o fluxo para o bloco seguinte de acordo com o parâmetro next de cada item de conditions. Exemplo, se o valor da variável ack for "Sim", o próximo bloco processado pelo chatbot será aquele cujo id é 4. 

Temos  em conditions uma propriedade especial com valor default. Se o valor de ack não for localizado em nenhum item de conditions, será considerado, portanto, o valor de default, no caso do exemplo 24. Lembrando que o valor de next neste caso é o id do bloco seguinte a ser processado. 

Bloco de encerramento

O bloco de encerramento de fluxo serve para indicar ao Tolvnow que seu fluxo encerrou. Ele não é obrigatório, uma vez que caso o Tolvnow não localize em algum momento um bloco indicado como next, o fluxo será automaticamente encerrado.  Veja o exemplo:

​{
  "id": 11,
  "type": "end",
  "data": {
    "text": "Sessão encerrada."
  }
}

A propriedade data.text indica a mensagem que será exibida ao usuário quando o fluxo for encerrado.