Centro de ayuda
Chat API

Bot Talk API

Última actualización:

Bot Talk API

La Bot Talk API es una API REST para comunicarte con un chatbot específico desde tu propia aplicación - aplicaciones personalizadas, herramientas internas o automatizaciones que construyas tú mismo. Creas una clave de API en la pestaña API del bot y luego llamas al endpoint de chat utilizando la clave como token Bearer para obtener las respuestas del bot, ya sea en una respuesta única o transmitidas mediante streaming a través de SSE.

Primeros pasos

  1. Selecciona tu chatbot y ve a la pestaña API en la parte superior de la página del bot (Select Bot > API [Seleccionar bot > API]).

Pestaña Bot Talk API

  1. Haz clic en Create API Key (Crear clave de API).

Pestaña API con el botón Create API Key destacado

El contador junto al botón muestra cuántas claves están activas ("1 of 5 API keys active"). El enlace View API Documentation (Ver documentación de la API) abre esta referencia, y el fragmento de curl en Quick Start (Inicio rápido) te proporciona un ejemplo listo para ejecutar.

  1. En el cuadro de diálogo Create API Key, asigna un nombre a la clave, define opcionalmente una lista blanca de IP y un límite de peticiones (rate limit), elige qué permisos tendrá y haz clic en Create (Crear).

Cuadro de diálogo Create API Key

  1. Copia la clave completa desde el cuadro de diálogo de confirmación. El texto en claro solo se muestra una vez.

Una clave tiene un formato similar a ck_abcdefghijklmnopqrstuvwxyz012345. Cada clave pertenece a ese bot en particular, por lo que cada petición realizada con la clave se comunica con ese bot - el bot se identifica mediante la clave y nunca aparece en la URL.

URL base

https://api.chatlab.com/aichat

Todos los endpoints de este artículo son relativos a esta URL base.

Permisos de la clave

Cada clave cuenta con uno o ambos permisos, configurados mediante los interruptores en el cuadro de diálogo Create API Key:

  • Chat (send messages and receive responses) [Chat (enviar mensajes y recibir respuestas)] - permite el acceso a los endpoints /v1/chat y /v1/chat/stream.
  • Conversation history (list and read past conversations) [Historial de conversaciones (listar y leer conversaciones pasadas)] - permite el acceso a los endpoints /v1/conversations.

La pestaña API muestra los permisos otorgados a cada clave como insignias de Chat y Conversations (Conversaciones).

Autenticación

Envía la clave en el encabezado Authorization en cada petición:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Las peticiones sin un encabezado Authorization: Bearer ... devuelven 401 missing_api_key. Las claves desconocidas devuelven 401 invalid_api_key; las claves revocadas devuelven 401 revoked_api_key. Cinco intentos no válidos en un minuto desde la misma IP activan un bloqueo de 60 minutos.

Límites

  • Máximo 5 claves de Bot Talk activas por bot
  • Máximo 60 peticiones por minuto por clave (token bucket, capacidad de 60, reposición uniforme a 1 token por segundo). Configurable hacia abajo en el momento de la creación: define un valor inferior en rateLimitPerMinute y el límite se reducirá, adaptándose también la tasa de reposición.
  • Longitud máxima del mensaje: 4.000 caracteres
  • Los flujos SSE concurrentes por clave están sujetos a los límites de tu cuenta

Endpoints

POST /v1/chat

Envía un mensaje al bot y recibe la respuesta completa en una única respuesta JSON.

Cuerpo de la petición (Request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - cadena obligatoria, máximo 4.000 caracteres.
  • conversationId - UUID opcional. Omítelo para iniciar una nueva conversación; reutiliza el valor devuelto previamente por el servidor para añadir mensajes a una existente.
  • metadata - objeto opcional: {source, userName, userEmail, userPhone}. userEmail también se utiliza para derivar el ID de cliente interno.

Cuerpo de la respuesta (Response body - 200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role siempre es "assistant"; message.content es la respuesta completa.
  • model es el identificador del modelo en el que se ejecutó el bot para esta llamada.
  • usage.creditsUsed contabiliza el mensaje del usuario + la respuesta del bot (normalmente 2), más un crédito adicional por cada llamada a herramienta ejecutada.
  • actions lista las ejecuciones de herramientas que se realizaron durante este turno. Actualmente solo se emiten entradas de tipo function_call (con type, name, status: "completed").

POST /v1/chat/stream

Variante en streaming de /v1/chat. Devuelve Content-Type: text/event-stream con Server-Sent Events.

Cuerpo de la petición (Request body)

Misma estructura que en POST /v1/chat. El indicador stream en el cuerpo no es necesario: usar esta ruta es lo que activa SSE.

Cuerpo de la respuesta (Eventos SSE)

  • message.delta - fragmento de contenido { "content": "..." }. Se envían varios a medida que llegan los tokens.
  • action - ejecución de herramienta { "type", "name", "status": "executing" }. Se emite cuando el bot activa una llamada a función.
  • message.done - evento final con conversationId, model, usage y (si las hay) la lista de actions completadas.
  • error - se envía si falla la generación; la transmisión termina después.

Se envían comentarios SSE de mantenimiento de conexión (:keepalive) cada 15 segundos durante generaciones prolongadas. Tiempos de espera (timeouts) del lado del servidor: 30 segundos para el primer token, 120 segundos en total por cada transmisión.

Ejemplo de curl

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Lista las conversaciones del bot asociado a tu clave, en todos los orígenes (widget, WhatsApp, API, etc.).

Parámetros de consulta (Query parameters)

  • limit - 1-100, por defecto 20. Los valores fuera de este rango se ajustan a los límites.
  • cursor - valor opaco devuelto en nextCursor en la página anterior. Omítelo para la primera página.

Cuerpo de la respuesta (Response body - 200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview se trunca a 100 caracteres con el sufijo ....
  • nextCursor es null en la última página; envíalo como cursor para obtener la siguiente.

GET /v1/conversations/{conversation_id}

Historial completo de la conversación.

Cuerpo de la respuesta (Response body - 200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Solo se devuelven los roles user y assistant; los mensajes internos del sistema (system) y de herramientas se filtran. Devuelve 404 not_found_error si la conversación no pertenece al bot vinculado a tu clave.

Para inspeccionar la configuración del bot, utiliza el endpoint de la Management API GET /v1/management/bots/{bot_id} con una clave de administración (Management key).

Encabezados de rate limit

Las respuestas que alcanzan la fase de rate limit (es decir, tras superar la autenticación y la lista blanca de IP) incluyen:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - el límite por clave aplicado efectivamente a esta llamada (60 por defecto, o el valor configurado en rateLimitPerMinute si es menor).
  • X-RateLimit-Remaining - tokens restantes en el bucket inmediatamente después de esta llamada.
  • X-RateLimit-Reset - marca de tiempo Unix en segundos en la que el siguiente token estará disponible (no es un restablecimiento completo del bucket; este se rellena continuamente). Cuando el bucket está lleno, coincide con la hora actual.

En las respuestas 429 rate_limit_exceeded, también se incluye Retry-After, expresado en segundos enteros hasta que se libere al menos un token.

Los errores previos a la autenticación (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) y 403 ip_not_whitelisted no incluyen los encabezados X-RateLimit-*; el limitador solo se consulta tras validar con éxito la autenticación y las comprobaciones de IP.

Formato de errores

Todos los errores comparten una estructura común:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Códigos HTTP habituales:

  • 400 invalid_request_error - entrada mal formada (códigos: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - falta la clave (missing_api_key), clave desconocida (invalid_api_key) o clave revocada (revoked_api_key)
  • 402 quota_exceeded_error - créditos de mensajes agotados
  • 403 permission_error - IP bloqueada (ip_blocked), IP no incluida en la lista blanca de la clave (ip_not_whitelisted) o el tipo de clave no permite este endpoint (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - la conversación no pertenece a este bot
  • 405 invalid_request_error (method_not_allowed) - verbo HTTP incorrecto en la URL
  • 429 rate_limit_error - demasiadas peticiones (rate_limit_exceeded) o demasiadas transmisiones concurrentes (concurrent_streams_exceeded)
  • 500 api_error - error interno

Temas relacionados

Para operaciones a nivel de cuenta (crear bots, actualizar bots, consultar el consumo), consulta la Management API.

Buscar en todos los artículosPregunta al agente