Endpoint Tolky Reasoning

O endpoint Tolky Reasoning é o coração da nossa API de processamento de linguagem natural. Ele permite que você integre a inteligência do Tolky em suas aplicações, mantendo o contexto das conversas e oferecendo respostas personalizadas e naturais.

​

📑 Índice

• 🎯 Visão Geral
• 🔑 Autenticação
• ⚙️ Parâmetros da Requisição
• 📦 Estrutura da Resposta
• 💡 Exemplos de Uso
• ⚠️ Tratamento de Erros
• ✨ Boas Práticas

​

🎯 Visão Geral

O endpoint Tolky Reasoning é responsável por:

​

🔑 Autenticação

Para utilizar o endpoint, é necessário incluir um token de autenticação no header da requisição:

Authorization: Bearer {seu-token-de-acesso}

​

⚙️ Parâmetros da Requisição

​

📋 Parâmetros Obrigatórios

​

🔧 Parâmetros Opcionais

• ⚙️ reasoningConfig

• 👤 userData

{
  "rebounce": boolean,
  "rebounceInstructions": string,
  "returnDialogue": boolean,
  "tolkyCompleteLog": boolean
}

​

📦 Estrutura da Resposta

A resposta da API segue o seguinte formato:

{
  "code": 200,
  "message": "Success",
  "data": {
    "assistantResponse": {
      "string": "Resposta do assistente",
      "wppParsed": {},
      "isAudio": false
    },
    "tokensControl": [
      {
        "model": "string",
        "tokens": number
      }
    ],
    "sessionId": "string",
    "conversationId": "string",
    "hostId": "string",
    "tickets": {
      "ticketId": "string",
      "ticketDescription": "string"
    },
    "userId": "string",
    "leadId": "string",
    "askHumanHelp": boolean,
    "jsonArray": [],
    "agentsLog": [],
    "restStatus": [],
    "conversation": [],
    "question": "string",
    "tolkyCompleteLog": []
  }
}

​

🔄 Processamento de Markdown

O campo wppParsed na resposta é o resultado do processamento do campo string através do markdownParser. Este parser converte o texto markdown em um array de objetos estruturados para exibição no WhatsApp, com suporte aos seguintes tipos de conteúdo:

​

Tipos de Conteúdo Suportados

1. Texto (type: "text")

   • Conteúdo de texto simples
   • Suporte a formatação em negrito usando *texto*
   • Títulos são convertidos para texto em negrito

2. Imagens (type: "image")

   • Suporta imagens em formatos: jpg, jpeg, png, gif, webp
   • Sintaxe markdown: ![descrição](url-da-imagem)
   • Inclui descrição e URL da imagem

3. Links (type: "site")

   • Links para sites web
   • Sintaxe markdown: [descrição](url)
   • Inclui descrição e URL do link

4. Áudio (type: "audio")

   • Suporta formatos: mp3, wav, ogg
   • Sintaxe markdown: [descrição](url-do-audio)
   • Inclui descrição e URL do áudio

5. Boleto (type: "boleto")

   • Detecta automaticamente linhas digitáveis de boletos
   • Formato: 47 ou 48 dígitos com espaços/pontos

6. PIX (type: "pix")

   • Detecta automaticamente códigos PIX Copia e Cola
   • Formato: começa com “000201” e termina com CRC16

​

Funcionalidades do Parser

O parser também:

• Normaliza quebras de linha e URLs
• Mantém a formatação de parágrafos
• Preserva a estrutura de bullets e listas numeradas
• Trata URLs “soltas” no texto
• Converte formatação markdown para o formato aceito pelo WhatsApp

​

Exemplo de Resposta com wppParsed

{
  "assistantResponse": {
    "string": "Olá! Aqui está sua fatura: ![Fatura](https://exemplo.com/fatura.jpg)\n\nPara pagar, você pode usar o PIX: 000201...6304ABCD\n\nOu o boleto: 12345.67890 12345.678901 12345.678901 1 12345678901234",
    "wppParsed": [
      {
        "type": "text",
        "content": "Olá! Aqui está sua fatura:"
      },
      {
        "type": "image",
        "content": "https://exemplo.com/fatura.jpg",
        "url": "https://exemplo.com/fatura.jpg",
        "description": "Fatura"
      },
      {
        "type": "text",
        "content": "Para pagar, você pode usar o PIX:"
      },
      {
        "type": "pix",
        "content": "000201...6304ABCD"
      },
      {
        "type": "text",
        "content": "Ou o boleto:"
      },
      {
        "type": "boleto",
        "content": "12345.67890 12345.678901 12345.678901 1 12345678901234"
      }
    ],
    "isAudio": false
  }
}

​

💡 Exemplos de Uso

• 📤 Requisição Básica

• 📤 Requisição com Token de Domínio

• 📥 Resposta

curl -X POST \
  '{BASE_URL}/api/externalAPIs/public/tolkyReasoning' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {seu-token}' \
  -d '{
    "hostId": "uuid-do-host",
    "conversationId": "uuid-da-conversa",
    "question": "Sua pergunta aqui",
    "originalDialogue": [],
    "contextData": "Dados de contexto",
    "userData": {
      "userName": "Nome do Usuário",
      "email": "usuario@email.com"
    }
  }'

​

⚠️ Tratamento de Erros

​

Exemplo de Erro com Token de Domínio

Quando um token de domínio é utilizado sem especificar o choosenHostId, a API retornará um erro 409 com a lista de hosts disponíveis:

{
  "code": 409,
  "message": "Host não especificado para token de domínio",
  "data": {
    "availableHosts": [
      {
        "host_id": "uuid-do-host-1",
        "host_slug": "host-1",
        "host_name": "Nome do Host 1"
      },
      {
        "host_id": "uuid-do-host-2",
        "host_slug": "host-2",
        "host_name": "Nome do Host 2"
      }
    ]
  }
}

​

⏱️ Timeout

Todas as requisições têm um timeout de 60 segundos. Se a requisição exceder este limite, será retornado um erro 408 (Request Timeout).

​

✨ Boas Práticas

​

🔄 Endpoints Relacionados

​

Criar ID de Conversa

Cria um novo ID de conversa para o processamento do Tolky Reasoning.

Endpoint: POST /api/externalAPIs/public/createConversationId

Ver documentação completa

​

Listar Agentes

Retorna informações sobre os agentes disponíveis para um host específico.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/agentsListHelper

Ver documentação completa

​

Obter Templates de Fluxo Padrão

Retorna os templates de fluxo padrão disponíveis no sistema.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/getDefaultChains

Ver documentação completa

​

Listar Fluxos

Retorna informações sobre os fluxos de um host específico.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/decisionChainsListHelper

Ver documentação completa

​

Salvar Fluxo

Salva um novo fluxo ou edita um fluxo existente.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/saveDecisionChainHelper

Ver documentação completa

​

Listar Modelos

Retorna informações sobre os modelos disponíveis para processamento.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/modelsListHelper

Ver documentação completa

​

Criar Chunk

Cria um novo chunk de conversa para processamento.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/createChunkHelper

Ver documentação completa

​

Editar Chunk

Edita um chunk de conversa existente.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/editChunkHelper

Ver documentação completa

​

Ler Chunks

Retorna os chunks de uma conversa específica.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/readChunksHelper

Ver documentação completa

​

Criar Sub-avatar

Cria um novo sub-avatar para personalização de respostas.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/createSubAvatarHelper

Ver documentação completa

​

Listar Avatares

Retorna informações sobre os avatares disponíveis.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/avatarsListHelper

Ver documentação completa

​

Obter Informações da Conversa

Retorna informações detalhadas sobre uma conversa específica.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/getConversationInformationHelper

Ver documentação completa