Obtener Historial de Chat por Agente

Recupera el historial de conversaciones de un agente de IA específico.

Endpoint

GET /api/v1/chat-history/agent/{agentId}

Autenticación

Este endpoint requiere autenticación con API key. Incluye tu API key en el encabezado Authorization usando el esquema Bearer.

Formato del Encabezado:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Solicitud

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`agentId`	string (UUID)	Sí	El identificador único del agente

Encabezados

Encabezado	Tipo	Requerido	Descripción
`Authorization`	string	Sí	Tu API key en el formato `Bearer pk_xxx:sk_xxx`

Parámetros de Consulta

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`page`	integer	No	1	Número de página para la paginación
`limit`	integer	No	50	Número de mensajes a devolver por página (máx: 100)
`thread_id`	string	No	-	Filtrar por ID de hilo/conversación específico
`start_date`	string (ISO 8601)	No	-	Filtrar mensajes desde esta fecha en adelante
`end_date`	string (ISO 8601)	No	-	Filtrar mensajes hasta esta fecha

Respuesta

Respuesta Exitosa

Código de Estado: 200 OK

Cuerpo de la Respuesta:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "440e8400-e29b-41d4-a716-446655440099",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "thread_id": "thread_abc123xyz",
        "input": "What are your business hours?",
        "output": "Our business hours are Monday to Friday, 9 AM to 6 PM EST.",
        "input_tokens": 8,
        "output_tokens": 15,
        "total_credits": 3,
        "created_at": "2024-01-20T14:30:00Z",
        "channel": "API"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440088",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "thread_id": "thread_abc123xyz",
        "input": "Do you offer technical support?",
        "output": "Yes, we offer 24/7 technical support for all our customers. You can reach us via email, phone, or live chat.",
        "input_tokens": 7,
        "output_tokens": 22,
        "total_credits": 3,
        "created_at": "2024-01-20T14:32:15Z",
        "channel": "API"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 2,
      "has_more": false
    }
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la solicitud fue exitosa
`data.messages`	array	Arreglo de objetos de mensaje
`data.messages[].id`	string (UUID)	Identificador único del mensaje
`data.messages[].agent_id`	string (UUID)	ID del agente que procesó el mensaje
`data.messages[].thread_id`	string	Identificador del hilo de conversación
`data.messages[].input`	string	Mensaje de entrada del usuario
`data.messages[].output`	string	Mensaje de respuesta del agente
`data.messages[].input_tokens`	integer	Número de tokens en la entrada
`data.messages[].output_tokens`	integer	Número de tokens en la salida
`data.messages[].total_credits`	integer	Total de créditos consumidos para este mensaje
`data.messages[].created_at`	string (ISO 8601)	Marca de tiempo de cuándo se creó el mensaje
`data.messages[].channel`	string	Canal donde se originó el mensaje (API, WEB, WHATSAPP)
`data.pagination`	object	Información de paginación
`data.pagination.page`	integer	Número de página actual
`data.pagination.limit`	integer	Número de elementos por página
`data.pagination.total`	integer	Número total de mensajes
`data.pagination.has_more`	boolean	Si hay más páginas disponibles

Respuestas de Error

401 Unauthorized

API Key Faltante o Inválida:

Status: 401 Unauthorized
{
  "success": false,
  "error": "Invalid or missing API key"
}

403 Forbidden

Agente No Pertenece a la Organización:

Status: 403 Forbidden
{
  "success": false,
  "error": "Agent does not belong to your organization"
}

404 Not Found

Agente No Encontrado:

Status: 404 Not Found
{
  "success": false,
  "error": "Agent not found"
}

400 Bad Request

Parámetros Inválidos:

Status: 400 Bad Request
{
  "success": false,
  "error": "Invalid page or limit parameter"
}

500 Internal Server Error

Status: 500 Internal Server Error
{
  "success": false,
  "error": "Internal server error"
}

Ejemplos de Uso

cURL

# Get first page of chat history
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get chat history with pagination
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?page=2&limit=25" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Filter by thread ID
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?thread_id=thread_abc123xyz" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Filter by date range
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

// Basic request
fetch(`https://agentsgt.com/api/v1/chat-history/agent/${agentId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Found ${data.data.messages.length} messages`);
    data.data.messages.forEach(msg => {
      console.log(`[${msg.created_at}] User: ${msg.input}`);
      console.log(`[${msg.created_at}] Agent: ${msg.output}`);
    });
  })
  .catch(error => {
    console.error('Error:', error);
  });

// With pagination and filters
const params = new URLSearchParams({
  page: '1',
  limit: '25',
  thread_id: 'thread_abc123xyz'
});

fetch(`https://agentsgt.com/api/v1/chat-history/agent/${agentId}?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Chat history:', data.data.messages);
    console.log('Has more:', data.data.pagination.has_more);
  });

Python (Requests)

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

# Basic request
response = requests.get(
    f'https://agentsgt.com/api/v1/chat-history/agent/{agent_id}',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Found {len(data['data']['messages'])} messages")

    for msg in data['data']['messages']:
        print(f"\n[{msg['created_at']}]")
        print(f"User: {msg['input']}")
        print(f"Agent: {msg['output']}")
        print(f"Credits used: {msg['total_credits']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

# With filters
params = {
    'page': 1,
    'limit': 25,
    'thread_id': 'thread_abc123xyz',
    'start_date': '2024-01-01T00:00:00Z',
    'end_date': '2024-01-31T23:59:59Z'
}

response = requests.get(
    f'https://agentsgt.com/api/v1/chat-history/agent/{agent_id}',
    headers=headers,
    params=params
)

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

axios.get(`https://agentsgt.com/api/v1/chat-history/agent/${agentId}`, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  },
  params: {
    page: 1,
    limit: 50,
    thread_id: 'thread_abc123xyz'
  }
})
  .then(response => {
    const { messages, pagination } = response.data.data;

    console.log(`Page ${pagination.page} of chat history`);
    console.log(`Total messages: ${pagination.total}`);

    messages.forEach(msg => {
      console.log(`\nThread: ${msg.thread_id}`);
      console.log(`User: ${msg.input}`);
      console.log(`Agent: ${msg.output}`);
    });

    if (pagination.has_more) {
      console.log('\nMore messages available on next page');
    }
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notas

Los mensajes se devuelven en orden ascendente por fecha de creación (los más antiguos primero)
El límite máximo es de 100 mensajes por página
El thread_id representa una sesión de conversación única
Todos los mensajes deben pertenecer a agentes de tu organización
Los filtros de fecha usan el formato ISO 8601 con información de zona horaria
La marca de tiempo last_used_at de la API key se actualiza automáticamente cuando se llama a este endpoint

Endpoints Relacionados

Obtener Historial de Chat por Identificador - Recupera el historial de chat de un identificador de usuario/sesión específico
Obtener Todos los Agentes - Lista todos los agentes de tu organización

Endpoint​

Autenticación​

Solicitud​

Parámetros de Ruta​

Encabezados​

Parámetros de Consulta​

Respuesta​

Respuesta Exitosa​

Campos de la Respuesta​

Respuestas de Error​

401 Unauthorized​

403 Forbidden​

404 Not Found​

400 Bad Request​

500 Internal Server Error​

Ejemplos de Uso​

cURL​

JavaScript (Fetch API)​

Python (Requests)​

Node.js (Axios)​

Notas​

Endpoints Relacionados​