A rota investigateMessage é uma API pública que permite investigar detalhadamente uma mensagem específica através do seu ID. Esta rota fornece informações completas sobre a mensagem, incluindo dados de controle de requisição, custos de IA, chamadas de APIs externas e métricas de performance. Além disso, oferece a opção de análise com IA para explicar como cada parte da mensagem foi gerada.


📑 Índice


🎯 Visão Geral

Endpoint

POST /api/externalAPIs/public/investigateMessage

Funcionalidades Principais


🔑 Autenticação

A rota utiliza autenticação via Bearer Token através do middleware tolkyAuthMiddleware. O token deve ser enviado no cabeçalho Authorization.

Cabeçalhos Obrigatórios

Authorization: Bearer <seu_token_aqui>
Content-Type: application/json

⚙️ Parâmetros da Requisição

Body (JSON)

CampoTipoObrigatórioDescrição
messageIdstring (UUID)SimID único da mensagem a ser investigada
useAIbooleanNãoSe true, inclui análise com IA explicando como a mensagem foi gerada (padrão: false)

📦 Estrutura da Resposta

Resposta de Sucesso (Análise Básica)

{
  "success": true,
  "data": {
    "host_slug": "exemplo-host",
    "time_ranking": [1.2, 0.8, 2.1],
    "tolky_recap": "Resumo da conversa gerado pela IA",
    "message": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "conversation_id": "456e7890-e89b-12d3-a456-426614174001",
      "role": "assistant",
      "content": "Conteúdo da mensagem",
      "description": "Descrição da mensagem",
      "transcription": "Transcrição de áudio se aplicável",
      "url": "https://exemplo.com/arquivo",
      "host_id": "789e0123-e89b-12d3-a456-426614174002",
      "avatar_id": "012e3456-e89b-12d3-a456-426614174003",
      "request_control_id": "345e6789-e89b-12d3-a456-426614174004",
      "responder": "avatar-name",
      "campaign_id": "678e9012-e89b-12d3-a456-426614174005",
      "status": "delivered",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "deleted": false
    },
    "iaRequests": [
      {
        "id": "901e2345-e89b-12d3-a456-426614174006",
        "model": "gpt-4",
        "caller": "conversation-handler",
        "payload": {
          "messages": [...],
          "temperature": 0.7
        },
        "response": "Resposta da IA",
        "prompt_tokens": 150,
        "completion_tokens": 75,
        "total_tokens": 225,
        "cost": 0.0034,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "externalApiRequests": [
      {
        "request": "curl -X POST 'https://api.exemplo.com/endpoint' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"param\": \"value\"}'",
        "response": {
          "status": 200,
          "data": {...}
        }
      }
    ],
    "control": {
      "totalInputTokens": 150,
      "totalOutputTokens": 75,
      "timeControl": {
        "startTime": "2024-01-15T10:30:00Z",
        "endTime": "2024-01-15T10:30:05Z",
        "duration": 5000
      },
      "tolkyRequestLog": [
        "Log de requisição 1",
        "Log de requisição 2"
      ],
      "responseStatus": {
        "ok": true,
        "status": "delivered"
      },
      "promptChunkData": {
        "chunks": [...],
        "metadata": {...}
      }
    }
  }
}

Descrição Detalhada dos Campos

Campos Principais

  • host_slug: Slug identificador do host proprietário da mensagem
  • time_ranking: Array com métricas de tempo de processamento
  • tolky_recap: Resumo da conversa gerado pela IA Tolky
  • message: Objeto completo da mensagem investigada
  • iaRequests: Array com todas as requisições de IA realizadas
  • externalApiRequests: Array com chamadas para APIs externas (formatadas como curl)
  • control: Objeto com métricas e dados de controle

Objeto message

Contém todos os dados da mensagem do banco de dados:

CampoTipoDescrição
idstring (UUID)ID único da mensagem
conversation_idstring (UUID)ID da conversa à qual a mensagem pertence
rolestringPapel da mensagem (user, assistant, system)
contentstringConteúdo textual da mensagem
descriptionstringDescrição adicional da mensagem
transcriptionstringTranscrição de áudio (se aplicável)
urlstringURL de arquivo anexo (se aplicável)
host_idstring (UUID)ID do host proprietário
avatar_idstring (UUID)ID do avatar que processou a mensagem
request_control_idstring (UUID)ID do controle de requisição
responderstringNome do avatar responsável pela resposta
campaign_idstring (UUID)ID da campanha (se aplicável)
statusstringStatus da mensagem (delivered, failed, pending)
created_atstring (ISO 8601)Data de criação
updated_atstring (ISO 8601)Data da última atualização
deletedbooleanFlag indicando se a mensagem foi deletada

Array iaRequests

Contém todas as requisições de IA realizadas para processar a mensagem, ordenadas por data de criação:

CampoTipoDescrição
idstring (UUID)ID único da requisição de IA
modelstringModelo de IA utilizado (gpt-4, gpt-3.5-turbo, etc.)
callerstringIdentificador do componente que fez a chamada
payloadobjectDados enviados para a IA
responsestringResposta recebida da IA
prompt_tokensnumberNúmero de tokens de entrada
completion_tokensnumberNúmero de tokens de saída
total_tokensnumberTotal de tokens utilizados
costnumberCusto da requisição em USD
createdAtstring (ISO 8601)Data da requisição

Array externalApiRequests

Contém todas as chamadas para APIs externas realizadas, formatadas como comandos curl:

CampoTipoDescrição
requeststringComando curl da requisição para API externa
responseobjectResposta recebida da API externa (formato JSON)

Objeto control

Contém métricas e dados de controle:

CampoTipoDescrição
totalInputTokensnumberTotal de tokens de entrada utilizados
totalOutputTokensnumberTotal de tokens de saída utilizados
timeControlobjectMétricas de tempo de processamento
tolkyRequestLogarrayLog detalhado das requisições Tolky
responseStatusobjectStatus da resposta (ok, status)
promptChunkDataobjectDados dos chunks de prompt utilizados

🤖 Análise com IA

Quando useAI: true, a resposta inclui um campo adicional aiAnalysis:

{
  "success": true,
  "data": {
    // ... todos os campos da análise básica ...
    "aiAnalysis": {
      "analysis": {
        "json": {
          "analyzed_parts": [
            {
              "conversation_part": "Primeira parte da mensagem gerada",
              "payload_contributions": [
                "Conteúdo específico do payload que influenciou esta parte",
                "Outro elemento relevante do payload"
              ],
              "reasoning": "Explicação detalhada do raciocínio por trás desta parte da resposta"
            },
            {
              "conversation_part": "Segunda parte da mensagem gerada",
              "payload_contributions": [
                "Elementos do payload que contribuíram para esta parte"
              ],
              "reasoning": "Explicação do raciocínio para esta parte"
            }
          ]
        },
        "formato": "json"
      },
      "error": null,
      "tokens_used": {
        "prompt_tokens": 1200,
        "completion_tokens": 800,
        "total_tokens": 2000
      }
    }
  }
}

Objeto aiAnalysis

Contém a análise detalhada realizada pela IA:

CampoTipoDescrição
analysis.json.analyzed_partsarrayArray com partes analisadas da mensagem
analysis.json.analyzed_parts[].conversation_partstringParte específica da mensagem gerada
analysis.json.analyzed_parts[].payload_contributionsarrayElementos do payload que influenciaram esta parte
analysis.json.analyzed_parts[].reasoningstringExplicação do raciocínio por trás desta parte
tokens_usedobjectTokens utilizados na análise com IA

💡 Exemplos de Uso

  • 📤 Análise Básica

  • 📤 Com Análise IA

  • 📥 Resposta Básica

  • 📥 Resposta com IA

curl -X POST "https://api.tolky.com/api/externalAPIs/public/investigateMessage" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Exemplo Completo de Uso

#!/bin/bash

# Configurações
API_URL="https://api.tolky.com/api/externalAPIs/public/investigateMessage"
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
MESSAGE_ID="123e4567-e89b-12d3-a456-426614174000"

echo "🔍 Investigando mensagem básica..."
response_basic=$(curl -s -X POST "$API_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"messageId\": \"$MESSAGE_ID\"}")

if echo "$response_basic" | jq -e '.success' > /dev/null; then
    echo "✅ Investigação básica realizada com sucesso!"
    echo "Host: $(echo "$response_basic" | jq -r '.data.host_slug')"
    echo "Status: $(echo "$response_basic" | jq -r '.data.message.status')"
    echo "Total de tokens: $(echo "$response_basic" | jq -r '.data.control.totalInputTokens + .data.control.totalOutputTokens')"
    echo "Custo total IA: $(echo "$response_basic" | jq -r '[.data.iaRequests[].cost] | add')"
    echo "APIs externas chamadas: $(echo "$response_basic" | jq -r '.data.externalApiRequests | length')"
else
    echo "❌ Erro na investigação básica:"
    echo "$response_basic" | jq -r '.error.message'
    exit 1
fi

echo ""
echo "🤖 Investigando com análise IA..."
response_ai=$(curl -s -X POST "$API_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"messageId\": \"$MESSAGE_ID\", \"useAI\": true}")

if echo "$response_ai" | jq -e '.success' > /dev/null; then
    echo "✅ Análise com IA realizada com sucesso!"
    echo "Partes analisadas: $(echo "$response_ai" | jq -r '.data.aiAnalysis.analysis.json.analyzed_parts | length')"
    echo "Tokens usados na análise: $(echo "$response_ai" | jq -r '.data.aiAnalysis.tokens_used.total_tokens')"
    
    echo ""
    echo "📋 Resumo da análise:"
    echo "$response_ai" | jq -r '.data.aiAnalysis.analysis.json.analyzed_parts[] | "- \(.conversation_part): \(.reasoning)"'
else
    echo "❌ Erro na análise com IA:"
    echo "$response_ai" | jq -r '.error.message'
fi

⚠️ Tratamento de Erros

Erro de Autenticação (401)

{
  "success": false,
  "error": {
    "message": "Invalid credentials",
    "code": 401
  }
}

Erro de Validação (400)

{
  "success": false,
  "error": {
    "message": "Message ID is required",
    "code": 400
  }
}

Mensagem Não Encontrada (404)

{
  "success": false,
  "error": {
    "message": "Message not found for id: 123e4567-e89b-12d3-a456-426614174000",
    "code": 404
  }
}

Erro de Banco de Dados (500)

{
  "success": false,
  "error": {
    "message": "Failed to get message by id: connection timeout",
    "code": 500
  }
}

Erro na Análise IA

{
  "success": true,
  "data": {
    // ... dados básicos ...
    "aiAnalysis": {
      "analysis": null,
      "error": "RequestControl ou payload não disponível para análise",
      "tokens_used": null
    }
  }
}

🚀 Casos de Uso

Análise Básica (useAI: false ou omitido)

Análise com IA (useAI: true)


⚡ Cache e Performance

A rota implementa cache com TTL de 24 horas para otimizar performance:

  • Análise básica: messages/investigateMessageById/{messageId}
  • Análise com IA: messages/investigateMessageWithAI/{messageId}

Diferenças entre Análise Básica e com IA

AspectoAnálise BásicaAnálise com IA
VelocidadeRápida (cache de 60s)Mais lenta (chamada IA adicional)
CustoGratuitoConsome tokens adicionais
DadosDados brutos e métricasExplicação interpretativa
UsoDebug, auditoria, métricasCompreensão, otimização
Cache24 horas24 horas (separado)

🔒 Limitações

  • Requer autenticação válida com token Bearer
  • Mensagem deve existir e não estar deletada
  • Cache de 24 horas pode retornar dados não atualizados
  • Análise com IA consome tokens adicionais (modelo gpt-5-nano)
  • Dados sensíveis podem estar presentes nos logs de requisição
  • Análise com IA requer request_control e payload disponíveis

🔄 Endpoints Relacionados

Tolky Reasoning

Para processamento de perguntas e respostas contextualizadas utilizando a inteligência do Tolky.

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

Ver documentação completa

Smart Feedback

Para processamento assíncrono de múltiplas conversas com retomada inteligente.

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

Ver documentação completa