Endpoints de lectura

Los endpoints de lectura usan el bucket read (300 req/min) y solo exponen datos del tenant dueño de la API key.

Validar la API key

GET /channel/ping es un endpoint barato para health checks, wizards de setup y CI/CD. Valida la API key contra el servidor sin enviar mensaje al bot y sin consumir cuota de conversación.

GET /api/v1/channel/ping
Authorization: Bearer sk_live_YOUR_KEY
X-Overtaker-Version: 1

// 200 OK
{
  "tenant_id": "uuid-del-tenant",
  "tenant_name": "Mi Empresa S.A.",
  "channel_api_enabled": true,
  "api_version": "1"
}

Errores: 401 si la key es inválida/revocada · 403 si el plan no incluye Canal API.

Historial de conversación

GET /channel/conversations/{session_id}/messages devuelve los mensajes de la conversación más reciente del session_id en orden cronológico ascendente. Excluye mensajes internos del bot (tool calls).

GET /api/v1/channel/conversations/user-123/messages?limit=50
Authorization: Bearer sk_live_YOUR_KEY
X-Overtaker-Version: 1

Query params:

Param	Detalle
limit	Default 50, máximo 100 (fuera de rango → 400).
before	message_id cursor para paginar hacia atrás (opcional).

{
  "session_id": "user-123",
  "conversation_id": "conv-uuid",                  // null si no hay conversación
  "messages": [
    {
      "id": "msg-uuid",
      "role": "user",                              // "user" | "bot" | "agent"
      "text": "Hola, necesito ayuda",
      "message_type": "text",
      "created_at": "2026-05-27T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null                              // message_id para la siguiente página
}

Para paginar hacia atrás, pasá el cursor:

GET /api/v1/channel/conversations/user-123/messages?limit=50&before=msg-uuid-del-cursor

Snapshot del lead

GET /channel/leads/{lead_id} es útil cuando recibís un evento lead.captured —que es granular— y querés el snapshot completo del lead. Enforce de ownership por tenant.

GET /api/v1/channel/leads/lead-uuid-aqui
Authorization: Bearer sk_live_YOUR_KEY
X-Overtaker-Version: 1

// 200 OK
{
  "id": "lead-uuid",
  "full_name": "María González",
  "email": "maria@empresa.com",
  "phone": "+56912345678",
  "status": "ACTIVE",
  "funnel_stage": "QUALIFYING",
  "qualification_score": 75,
  "sentiment": "positive",
  "priority_label": "high",
  "value": 1500.0,
  "probability": 60,
  "captured_data": { "...": "..." },
  "tags": ["enterprise", "demo"],
  "last_contacted_at": "2026-05-27T12:00:00Z",
  "created_at": "2026-05-20T10:00:00Z",
  "updated_at": "2026-05-27T12:01:30Z"
}

Devuelve 404 si el lead no existe o pertenece a otro tenant.