Histórico de Mensajes

La API de Neoagent te permite recuperar el historial de mensajes de un chatbot enviando una solicitud POST al endpoint /chat/Chatbot/ChatContentHistory.

Tiempo de lectura

~3-4 minutos

Endpoint

URL de la Solicitud: https://app.neoagent.co/chat/Chatbot/ChatContentHistory
Método: POST

Headers requeridos

Authorization: <Your-Secret-Key> - cadena, obligatorio - La clave secreta para autenticar la solicitud API

Cuerpo de la Solicitud

{
  "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
  "StartTime": "2025-01-01",
  "EndTime": "2025-03-07"
}

Parámetros

SerialNumber - cadena, obligatorio - El identificador único del chatbot
StartTime - cadena, opcional - Fecha de inicio para el filtro (formato: YYYY-MM-DD, zona horaria UTC)
EndTime - cadena, opcional - Fecha de fin para el filtro (formato: YYYY-MM-DD, zona horaria UTC)

Sugerencia de Filtros

Si no se especifican StartTime y EndTime, la API devolverá todos los mensajes disponibles. Para mejorar el rendimiento, se recomienda limitar el rango temporal.

Ejemplos de Solicitud

JavaScript (Fetch API)
Python (Requests)
cURL
HTTP Raw

const res = await fetch('https://app.neoagent.co/chat/Chatbot/ChatContentHistory', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>"
  },
  body: JSON.stringify({
    "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
    "StartTime": "2025-01-01",
    "EndTime": "2025-03-07"
  })
});

const data = await res.json();
console.log(data);

import requests
import json

url = 'https://app.neoagent.co/chat/Chatbot/ChatContentHistory'
headers = {
  "Authorization": "<Your-Secret-Key>"
}
data = {
  "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
  "StartTime": "2025-01-01",
  "EndTime": "2025-03-07"
}

response = requests.post(url, headers=headers, json=data)
data = response.json()
print(data)

curl 'https://app.neoagent.co/chat/Chatbot/ChatContentHistory' \
  -X POST \
  -H 'Authorization: <Your-Secret-Key>' \
  -d '{"SerialNumber":"36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35","StartTime":"2025-01-01","EndTime":"2025-03-07"}'

POST /chat/Chatbot/ChatContentHistory HTTP/1.1
Host: app.neoagent.co
Authorization: <Your-Secret-Key>

{
  "SerialNumber": "36XXGxiYDigrQgg5xz4n45bcBW7qeYyW35",
  "StartTime": "2025-01-01",
  "EndTime": "2025-03-07"
}

Respuesta

La respuesta de la API será un objeto JSON con la siguiente estructura:

{
  // objeto - Mensajes en el período temporal del chatbot
  "Data": [
    {
      "SessionID": 31302,
      "CreateTime": "2023-11-21T16:22:42.264484Z",
      "URI": "xxx",
      "Messages": [
        {
          "Type": "AI",
          "Content": "¡Hola! ¿Cómo puedo ayudarte?"
        },
        {
          "Type": "User",
          "Content": "quiero reservar una cita"
        },
        {
          "Type": "AI",
          "Content": "¡Perfecto! Selecciona la fecha y la hora que prefieras..."
        }
      ]
    }
  ],
  // cadena - Versión API
  "Version": "1.0.0",
  // booleano - Estado de éxito de la operación
  "Success": true,
  // entero - Código de estado HTTP
  "Code": 200,
  // cadena - Mensaje de error si existe
  "Message": ""
}

Estructura de los Datos

Objeto de Sesión

SessionID - entero - Identificador único de la sesión de chat
CreateTime - cadena - Timestamp de creación de la sesión (formato ISO 8601 UTC)
URI - cadena - URI de la página web donde se llevó a cabo la conversación
Messages - array - Lista de los mensajes de la sesión

Objeto de Mensaje

Type - cadena - Tipo de mensaje ("AI" o "User")
Content - cadena - Contenido textual del mensaje

Casos de Uso

📊 Análisis de Conversaciones

async function analyzeConversations(serialNumber, startDate, endDate, apiKey) {
  const response = await fetch(/* llamada a la API */);
  const result = await response.json();
  
  if (result.Success) {
    const sessions = result.Data;
    
    // Estadísticas básicas
    const totalSessions = sessions.length;
    const totalMessages = sessions.reduce((sum, session) => sum + session.Messages.length, 0);
    const avgMessagesPerSession = totalMessages / totalSessions;
    
    // Análisis de tipos de solicitudes
    const userMessages = sessions.flatMap(s => 
      s.Messages.filter(m => m.Type === "User").map(m => m.Content)
    );
    
    console.log(`Análisis periodo ${startDate} - ${endDate}:`);
    console.log(`- Sesiones totales: ${totalSessions}`);
    console.log(`- Mensajes totales: ${totalMessages}`);
    console.log(`- Media de mensajes por sesión: ${avgMessagesPerSession.toFixed(2)}`);
    
    return { totalSessions, totalMessages, avgMessagesPerSession, userMessages };
  }
}

📈 Reportes Periódicos

async function generateMonthlyReport(serialNumber, month, year, apiKey) {
  const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
  const endDate = new Date(year, month, 0).toISOString().split('T')[0]; // Último día del mes
  
  const stats = await analyzeConversations(serialNumber, startDate, endDate, apiKey);
  
  // Genera el reporte
  const report = {
    period: `${month}/${year}`,
    metrics: stats,
    recommendations: generateRecommendations(stats)
  };
  
  return report;
}

function generateRecommendations(stats) {
  const recommendations = [];
  
  if (stats.avgMessagesPerSession < 3) {
    recommendations.push("📝 Las conversaciones son cortas - considera mejorar el engagement");
  }
  
  if (stats.totalSessions > 1000) {
    recommendations.push("🚀 Volumen alto - considera actualizar el plan para mejores rendimientos");
  }
  
  return recommendations;
}

🔍 Búsqueda y Filtrado

async function searchConversations(serialNumber, searchTerm, apiKey) {
  const response = await fetch(/* llamada a la API con rango temporal amplio */);
  const result = await response.json();
  
  if (result.Success) {
    const matchingSessions = result.Data.filter(session => 
      session.Messages.some(message => 
        message.Content.toLowerCase().includes(searchTerm.toLowerCase())
      )
    );
    
    return matchingSessions.map(session => ({
      sessionId: session.SessionID,
      date: new Date(session.CreateTime).toLocaleDateString('es-ES'),
      matchingMessages: session.Messages.filter(m => 
        m.Content.toLowerCase().includes(searchTerm.toLowerCase())
      )
    }));
  }
}

// Uso
const results = await searchConversations("36XXG...", "cita", "your-api-key");
console.log("Conversaciones con 'cita':", results);

Limitaciones y Rendimiento

Paginación

Esta API no soporta paginación nativa. Para gestionar grandes volúmenes de datos:

async function getHistoryInChunks(serialNumber, startDate, endDate, apiKey, chunkDays = 7) {
  const start = new Date(startDate);
  const end = new Date(endDate);
  const allSessions = [];
  
  while (start < end) {
    const chunkEnd = new Date(start);
    chunkEnd.setDate(chunkEnd.getDate() + chunkDays);
    if (chunkEnd > end) chunkEnd.setTime(end.getTime());
    
    const chunkData = await getChatHistory(
      serialNumber, 
      start.toISOString().split('T')[0],
      chunkEnd.toISOString().split('T')[0],
      apiKey
    );
    
    if (chunkData) allSessions.push(...chunkData);
    
    start.setDate(start.getDate() + chunkDays + 1);
  }
  
  return allSessions;
}

Limitación de Tasa

Límite recomendado: Máx 10 solicitudes/minuto para este endpoint
Estrategia: Implementa caching para reducir llamadas repetitivas
Procesamiento por lotes: Solicita períodos más largos en lugar de múltiples llamadas

Manejo de Errores

Si la solicitud falla, debes:

Verificar el código de estado HTTP para errores a nivel de red
Examinar los campos Code y Message en la respuesta para errores a nivel de negocio
El campo Message contendrá información detallada sobre el error

Posibles Errores

Código	Descripción	Acción Recomendada
400	Parámetros no válidos (fechas malformadas)	Verifica el formato de las fechas (YYYY-MM-DD)
401	Clave API no válida	Verifica las credenciales de autenticación
404	Chatbot no encontrado	Verifica que el SerialNumber sea correcto
413	Rango temporal demasiado amplio	Reduce el intervalo de fechas solicitado

Ejemplo de Manejo de Errores

async function safeGetChatHistory(serialNumber, startTime, endTime, apiKey) {
  try {
    const response = await fetch(/* ... */);
    const result = await response.json();
    
    if (!result.Success) {
      switch (result.Code) {
        case 413:
          console.warn('Rango demasiado amplio, reintentando con chunks más pequeños');
          return await getHistoryInChunks(serialNumber, startTime, endTime, apiKey);
        case 404:
          console.error('Chatbot no encontrado:', serialNumber);
          return null;
        default:
          console.error('Error API:', result.Message);
          return null;
      }
    }
    
    return result.Data;
  } catch (error) {
    console.error('Error de red:', error);
    return null;
  }
}

Zona Horaria

Todas las fechas en la API están en UTC. Asegúrate de convertir correctamente entre tu zona horaria local y UTC cuando sea necesario.

Endpoint​

Headers requeridos​

Cuerpo de la Solicitud​

Parámetros​

Ejemplos de Solicitud​

Respuesta​

Estructura de los Datos​

Objeto de Sesión​

Objeto de Mensaje​

Casos de Uso​

📊 Análisis de Conversaciones​

📈 Reportes Periódicos​

🔍 Búsqueda y Filtrado​

Limitaciones y Rendimiento​

Paginación​

Limitación de Tasa​

Manejo de Errores​

Posibles Errores​

Ejemplo de Manejo de Errores​