La API que usa el panel es la misma que puedes usar desde tu servidor. Todos los planes incluyen acceso a API; cada servicio aplica los permisos y límites de su contrato.

Base: https://my.talkhero.app/api

Autenticación

Crea una clave en Configuración → API keys. Se muestra una sola vez y se guarda como hash. Envíala como Bearer:

curl https://my.talkhero.app/api/agents \
  -H "Authorization: Bearer tk_live_xxx"

Cada clave pertenece a una cuenta; no necesitas indicar el tenant. Las claves se pueden revocar desde el panel y registran su último uso.

Convenciones

JSON en cuerpo y respuesta, content-type: application/json, excepto la carga y descarga de archivos, que utilizan bytes con application/octet-stream.
Validación estricta de entrada: un cuerpo inválido devuelve 400 con la lista de problemas.
Identificadores UUID v7 (ordenables por tiempo).
Fechas en ISO 8601 UTC.
Límite de tasa por cuenta y por IP; al superarlo recibes 429.
Los límites del plan (agentes, fuentes, flujos, puestos) se aplican en la API, no solo en la interfaz.

Recursos

Recurso	Ruta	Descripción
Agentes	`/agents`	Crear, editar, publicar o pausar agentes.
Conocimiento	`/knowledge`	Fuentes (markdown, URL, archivo), estado de indexación, reindexar.
Bandeja	`/inbox`	Conversaciones, hilo, tomar, responder, notas internas, asignar, cerrar.
Tickets	`/tickets`	Tickets con prioridad, SLA y vínculo a conversación.
Contactos	`/contacts`	Contactos con historial unificado.
Acciones	`/tools`	Herramientas HTTP que el agente puede invocar; prueba en modo dry run.
Flujos	`/flows`	Flujos declarativos, plantillas, activar/pausar, ejecuciones.
Respuestas guardadas	`/canned-replies`	Atajos `/nombre` para la bandeja.
Analítica	`/analytics/summary?period=AAAA-MM`	Métricas del periodo; `/analytics/export.csv` en Corporate.
Configuración	`/settings`	Widget, equipo, API keys, webhooks.
Archivos privados	`/v1/files`	Biblioteca, reserva de carga, contenido, comprobación y eliminación.

Ejemplos

Listar conversaciones esperando a una persona:

curl "https://my.talkhero.app/api/inbox?status=human" \
  -H "Authorization: Bearer tk_live_xxx"

Métricas del mes:

curl "https://my.talkhero.app/api/analytics/summary?period=2026-09" \
  -H "Authorization: Bearer tk_live_xxx"

{
  "period": "2026-09",
  "conversations": 120,
  "resolvedAuto": 84,
  "autonomousResolutionRate": 0.7,
  "avgFirstResponseMs": 1800,
  "avgCsat": 4.6,
  "llmCostUsd": 3.21,
  "costPerResolvedUsd": 0.0322,
  "topics": [{ "topic": "factura rechazada", "count": 31 }]
}

Los valores del ejemplo son ilustrativos del formato; las cifras reales salen de tu propia operación.

Streaming

El widget y el playground reciben las respuestas por SSE (text/event-stream) con eventos token, handoff, tool y done. Los eventos incluyen el texto parcial para pintarlo en cuanto llega.

Errores

Código	Significado
`400`	Cuerpo o parámetros inválidos.
`401`	Clave ausente, inválida o revocada.
`403`	La función no está en tu plan o tu rol no lo permite.
`404`	Recurso inexistente en tu cuenta.
`429`	Límite de tasa.