Investigar Mensagem por ID
API pública que permite investigar detalhadamente uma mensagem específica através do seu ID, incluindo dados de controle de requisição, custos de IA, chamadas de APIs externas e métricas de performance.
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
- 🔑 Autenticação
- ⚙️ Parâmetros da Requisição
- 📦 Estrutura da Resposta
- 🤖 Análise com IA
- 💡 Exemplos de Uso
- ⚠️ Tratamento de Erros
- 🚀 Casos de Uso
- ⚡ Cache e Performance
🎯 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)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
messageId | string (UUID) | Sim | ID único da mensagem a ser investigada |
useAI | boolean | Não | Se 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 mensagemtime_ranking: Array com métricas de tempo de processamentotolky_recap: Resumo da conversa gerado pela IA Tolkymessage: Objeto completo da mensagem investigadaiaRequests: Array com todas as requisições de IA realizadasexternalApiRequests: 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:
| Campo | Tipo | Descrição |
|---|---|---|
id | string (UUID) | ID único da mensagem |
conversation_id | string (UUID) | ID da conversa à qual a mensagem pertence |
role | string | Papel da mensagem (user, assistant, system) |
content | string | Conteúdo textual da mensagem |
description | string | Descrição adicional da mensagem |
transcription | string | Transcrição de áudio (se aplicável) |
url | string | URL de arquivo anexo (se aplicável) |
host_id | string (UUID) | ID do host proprietário |
avatar_id | string (UUID) | ID do avatar que processou a mensagem |
request_control_id | string (UUID) | ID do controle de requisição |
responder | string | Nome do avatar responsável pela resposta |
campaign_id | string (UUID) | ID da campanha (se aplicável) |
status | string | Status da mensagem (delivered, failed, pending) |
created_at | string (ISO 8601) | Data de criação |
updated_at | string (ISO 8601) | Data da última atualização |
deleted | boolean | Flag 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:
| Campo | Tipo | Descrição |
|---|---|---|
id | string (UUID) | ID único da requisição de IA |
model | string | Modelo de IA utilizado (gpt-4, gpt-3.5-turbo, etc.) |
caller | string | Identificador do componente que fez a chamada |
payload | object | Dados enviados para a IA |
response | string | Resposta recebida da IA |
prompt_tokens | number | Número de tokens de entrada |
completion_tokens | number | Número de tokens de saída |
total_tokens | number | Total de tokens utilizados |
cost | number | Custo da requisição em USD |
createdAt | string (ISO 8601) | Data da requisição |
Array externalApiRequests
Contém todas as chamadas para APIs externas realizadas, formatadas como comandos curl:
| Campo | Tipo | Descrição |
|---|---|---|
request | string | Comando curl da requisição para API externa |
response | object | Resposta recebida da API externa (formato JSON) |
Objeto control
Contém métricas e dados de controle:
| Campo | Tipo | Descrição |
|---|---|---|
totalInputTokens | number | Total de tokens de entrada utilizados |
totalOutputTokens | number | Total de tokens de saída utilizados |
timeControl | object | Métricas de tempo de processamento |
tolkyRequestLog | array | Log detalhado das requisições Tolky |
responseStatus | object | Status da resposta (ok, status) |
promptChunkData | object | Dados 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:
| Campo | Tipo | Descrição |
|---|---|---|
analysis.json.analyzed_parts | array | Array com partes analisadas da mensagem |
analysis.json.analyzed_parts[].conversation_part | string | Parte específica da mensagem gerada |
analysis.json.analyzed_parts[].payload_contributions | array | Elementos do payload que influenciaram esta parte |
analysis.json.analyzed_parts[].reasoning | string | Explicação do raciocínio por trás desta parte |
tokens_used | object | Tokens 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
| Aspecto | Análise Básica | Análise com IA |
|---|---|---|
| Velocidade | Rápida (cache de 60s) | Mais lenta (chamada IA adicional) |
| Custo | Gratuito | Consome tokens adicionais |
| Dados | Dados brutos e métricas | Explicação interpretativa |
| Uso | Debug, auditoria, métricas | Compreensão, otimização |
| Cache | 24 horas | 24 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_controlepayloaddisponí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
Smart Feedback
Para processamento assíncrono de múltiplas conversas com retomada inteligente.
Endpoint: POST /api/externalAPIs/public/tolkyReasoning/smartFeedback