Referencia de la REST API del Chatbot

REST API

Envía un mensaje a tu chatbot y recibe una respuesta generada por IA a través de HTTP estándar. Utilízalo para crear una interfaz de chat personalizada, una aplicación móvil o una automatización en el backend. Cada endpoint se sirve desde el mismo origen que el script de tu widget (https://webchatagent.com).

¿Utilizas JavaScript o TypeScript? El SDK de JavaScript (npm install webchatagent) envuelve estos endpoints con funciones tipadas, streaming y chat en vivo.

Cómo funciona una conversación

  1. Haz un POST con el message del usuario y tu chatbotId a /api/chat.
  2. Lee la respuesta (reply) en el cuerpo JSON. Lee la cabecera de respuesta X-Chat-Session-Id, ese es tu ID de sesión.
  3. Para el siguiente mensaje, envía el mismo ID de sesión en la cabecera de solicitud X-Chat-Session-Id. El servidor dispondrá entonces del contexto de la conversación: historial de mensajes, contexto de conocimiento respaldado por fuentes (generación aumentada por recuperación, RAG) y estado de chat en vivo.
  4. Repite el proceso. Omite la cabecera en cualquier momento en que desees iniciar una conversación nueva.

El servidor realiza el seguimiento del historial por sesión, por lo que solo necesitas enviar el último mensaje, nunca la transcripción completa.

Autenticación

La API utiliza autenticación basada en dominio: no requiere clave de API. Cada solicitud se comprueba con los Dominios permitidos configurados para el chatbot utilizando el Origin/Referer de la solicitud. Una solicitud procedente de un dominio no permitido recibe un código 403.

Para los chatbots de Wiki del Equipo IA con acceso protegido, envía también la cabecera X-Wiki-Auth con el token de autenticación de la wiki (el valor es wiki_auth_<subdomain>). Sin ella, las wikis protegidas devuelven un código 403.

Enviar un mensaje

POST https://webchatagent.com/api/chat

Cabeceras

CabeceraObligatorioDescripción
Content-TypeSíDebe ser application/json.
X-Chat-Session-IdNoID de sesión (un UUID) para dar continuidad a la conversación. Omítelo en la primera solicitud; la cabecera de respuesta devuelve uno nuevo. También puedes generar un UUID aleatorio por tu cuenta. Cualquier valor que no sea un UUID se reemplaza por una nueva sesión.
AcceptNotext/event-stream para recibir la respuesta como un flujo continuo (consulta Streaming).
Accept-LanguageNoIdioma preferido para la respuesta, por ejemplo de.

Cuerpo de la Solicitud

CampoTipoObligatorioDescripción
messagestringSíEl mensaje del usuario. Máximo 700 caracteres. No puede estar vacío.
chatbotIdstring (UUID)SíEl ID de tu chatbot, obtenido en la configuración del chatbot.
pageUrlstringNoLa URL completa de la página en la que se encuentra el visitante (window.location.href). Se utiliza para la recuperación contextualizada según la página; se valida frente a tus dominios permitidos.
contextDataobjectNoContexto plano de clave-valor sobre la sesión del visitante (máximo 20 claves, claves de 64 caracteres, valores string/number/boolean de 500 caracteres). Se inyecta en el prompt de la IA únicamente para esta solicitud, nunca se almacena como un registro propio; la IA trata los valores como datos, no como instrucciones, y puede utilizarlos en los argumentos de herramientas y conectores de API. Consulta Datos de contexto de sesión.

Ejemplo de solicitud

{
  "message": "What are your business hours?",
  "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Respuesta

El ID de sesión se devuelve en la cabecera de respuesta X-Chat-Session-Id, no en el cuerpo.

CampoTipoDescripción
replystringLa respuesta en formato Markdown. Puede terminar con un comentario HTML oculto <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> que contiene preguntas de seguimiento sugeridas: muestra label en un botón, envía text al hacer clic y elimina el comentario antes de renderizar.
sourcesarrayFuentes en las que se basó la respuesta (ver más abajo). Vacío si no se utilizó ninguna.
modestringModo de conversación: bot (la IA está respondiendo) o human (un agente en vivo ha tomado el control). Presente cuando corresponda.
statusstringEstado del chat en vivo: waiting, open o closed. Solo está presente cuando el Chat en vivo está activo en la sesión.
aiGeneratedbooleantrue cuando la IA redactó la respuesta. No aparece mientras un agente humano atiende la conversación.
conversationTooLongbooleanLa conversación alcanzó su límite de longitud. Inicia una nueva sesión.

Cuando un agente humano toma el control (mode: "human", status: "open"), el campo reply puede estar vacío, ya que el agente responde de forma independiente. Mientras el traspaso está en espera (waiting), la respuesta es un aviso breve como "Un miembro del equipo se unirá en breve."

Array de fuentes

Cada objeto de fuente contiene:

CampoTipoDescripción
typestringweb (una página del sitio web), product (datos estructurados de producto) o fileSource (un documento procedente del almacenamiento de archivos conectado).
sourcestringPara web: la URL de la página. Para product: el identificador del producto. Para fileSource: el ID del documento.
dataobjectSolo para product. Contiene id, dataType, format, data y sourceUrl.

Ejemplo de respuesta

{
  "reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
  "sources": [
    {
      "type": "web",
      "source": "https://example.com/contact"
    }
  ],
  "mode": "bot"
}

Streaming

Envía Accept: text/event-stream para recibir la respuesta a medida que se genera. Si el chatbot tiene el streaming habilitado, la respuesta es un flujo de Server-Sent Events, cada uno compuesto por una sola línea data: con un objeto JSON, separados por una línea en blanco:

data: {"type":"token","data":"Our business hours "}

data: {"type":"token","data":"are Monday to Friday."}

data: {"type":"done","reply":"Our business hours are Monday to Friday.","sources":[],"conversationTooLong":false,"aiGenerated":true}
typeCamposSignificado
tokendataSiguiente fragmento de la respuesta. Concaténalo. El texto puede contener Markdown incompleto y el comienzo del comentario de sugerencias.
tool_callnameEl bot está utilizando una herramienta, por ejemplo, una búsqueda de productos.
errordataUn problema. Por lo general le sigue un done; si la transmisión termina sin done, procesa data como el error.
donemismos campos que la respuesta JSONLa respuesta final. Reemplaza el texto recibido por streaming con reply.

El servidor responde con JSON sin procesar en lugar de un flujo continuo cuando el streaming está desactivado para el chatbot, cuando un agente humano gestiona la conversación y en caso de errores. Revisa el Content-Type de la respuesta. Cerrar la conexión detiene la generación.

Historial de chat

Obtén los mensajes almacenados para una sesión (por ejemplo, para restaurar una conversación tras recargar la página). El historial con más de 30 días de antigüedad se elimina por motivos de RGPD; una sesión caducada devuelve un código 410.

GET https://webchatagent.com/api/chat/history

Parámetros de consulta

ParámetroTipoObligatorioDescripción
chatbotIdstring (UUID)SíEl ID de tu chatbot.
sessionIdstring (UUID)SíLa sesión cuyo historial deseas obtener.

Respuesta

messages se ordena desde el más antiguo al más reciente. sender es bot o user (es un valor para visualización, no el rol en bruto). role corresponde al rol subyacente user / assistant / system, y isAgent es true cuando un mensaje de assistant procede de un agente humano en lugar de la IA.

{
  "messages": [
    {
      "id": 123,
      "sender": "user",
      "role": "user",
      "isAgent": false,
      "text": "What are your hours?",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": 124,
      "sender": "bot",
      "role": "assistant",
      "isAgent": false,
      "text": "Our hours are Monday to Friday, 9 AM to 5 PM.",
      "sources": [{ "type": "web", "source": "https://example.com/contact" }],
      "createdAt": "2025-01-15T10:30:01Z"
    }
  ]
}

sources solo aparece si el mensaje dispone de fuentes.

Información de la sesión

Obtén el recuento de mensajes y la última actividad de las sesiones conocidas por este navegador. Para evitar la filtración de chats de otros visitantes, debes transferir los ID de sesión que ya poseas (por ejemplo, desde el almacenamiento local). Las sesiones sin actividad en los últimos 30 días no se devuelven.

GET https://webchatagent.com/api/chat/sessions

Parámetros de consulta

ParámetroTipoObligatorioDescripción
chatbotIdstring (UUID)SíEl ID de tu chatbot.
sessionIdsstringSíUUID de sesión separados por comas (máximo 5; los adicionales se ignoran).

Respuesta

{
  "sessions": [
    {
      "sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "messageCount": 12,
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Reset Session History

Borre el Contexto de conversación en memoria de una sesión para que el siguiente mensaje inicie la IA desde cero (sin turnos previos). Esto no elimina los mensajes almacenados, ya que conversation_messages son datos de negocio y permanecen en la base de datos (y en /api/chat/history).

DELETE https://webchatagent.com/api/chat/session

Headers

HeaderRequiredDescription
X-Chat-Session-IdSíLa sesión cuyo historial en memoria se desea borrar.

Response

{ "success": true, "message": "Chat session cleared." }

Error Handling

La mayoría de los errores de /api/chat devuelven la misma estructura que una respuesta normal: un mensaje HTML descriptivo en reply y un array sources vacío. El código de estado HTTP indica el tipo de error real.

StatusMeaning
400Cuerpo no válido, campo faltante, mensaje vacío o mensaje de más de 700 caracteres.
403Dominio no permitido, fallo de autenticación de wiki o se aplica una restricción del plan.
404Chatbot no encontrado.
429Límite de tasa alcanzado o se alcanzó la cuota mensual de mensajes.
502El proveedor de IA (LLM) devolvió un error.

Error Response Body

{
  "reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
  "sources": []
}

Las solicitudes no válidas (400), el límite de tasa (429) y las direcciones IP bloqueadas (403) devuelven en su lugar un cuerpo diferente: { "error": true, "statusCode": 429, "message": "..." }. Bifurque la lógica primero según el código de estado HTTP y luego muestre reply o message al usuario.

Rate Limiting

ScopeLimit
Por sesión10 solicitudes por minuto
Por dirección IP15 solicitudes por minuto
Por sesión y por dirección IPal menos 1 segundo entre dos solicitudes

Superar cualquiera de estos límites devuelve 429. De forma independiente, alcanzar la cuota mensual de mensajes del plan también devuelve 429 (con un mensaje de "no disponible temporalmente").

Code Examples

cURL

# Send a message (capture the session id from the response header)
curl -i -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you offer?",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

# Continue the conversation (reuse the session id from above)
curl -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Chat-Session-Id: SESSION_ID_FROM_FIRST_RESPONSE" \
  -d '{
    "message": "Tell me more about the premium plan",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

JavaScript / TypeScript

async function chat(message, chatbotId, sessionId = null) {
  const headers = { 'Content-Type': 'application/json' };
  if (sessionId) headers['X-Chat-Session-Id'] = sessionId;

  const response = await fetch('https://webchatagent.com/api/chat', {
    method: 'POST',
    headers,
    body: JSON.stringify({ message, chatbotId })
  });

  const data = await response.json();
  // The session id lives in the response header — keep it for follow-up messages.
  const newSessionId = response.headers.get('X-Chat-Session-Id');

  return { ...data, sessionId: newSessionId || sessionId };
}

// First message
const result = await chat('Hello!', 'YOUR_CHATBOT_ID');
console.log(result.reply);

// Follow-up in the same conversation
const followUp = await chat('Tell me more', 'YOUR_CHATBOT_ID', result.sessionId);
console.log(followUp.reply);

Python

import requests

CHATBOT_ID = "YOUR_CHATBOT_ID"
URL = "https://webchatagent.com/api/chat"

# First message
response = requests.post(URL, json={
    "message": "What are your business hours?",
    "chatbotId": CHATBOT_ID,
})

data = response.json()
session_id = response.headers.get("X-Chat-Session-Id")
print("Reply:", data["reply"])
print("Sources:", data["sources"])

# Continue the conversation
response = requests.post(
    URL,
    json={"message": "And on weekends?", "chatbotId": CHATBOT_ID},
    headers={"X-Chat-Session-Id": session_id},
)
print("Reply:", response.json()["reply"])

PHP

<?php
$chatbotId = 'YOUR_CHATBOT_ID';
$url = 'https://webchatagent.com/api/chat';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'message'   => 'What are your business hours?',
        'chatbotId' => $chatbotId,
    ]),
    CURLOPT_HEADER => true, // include headers so we can read the session id
]);

$response   = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers    = substr($response, 0, $headerSize);
$body       = json_decode(substr($response, $headerSize), true);

echo 'Reply: ' . $body['reply'] . PHP_EOL;

// Pull the session id from the response headers for follow-up messages
preg_match('/X-Chat-Session-Id:\s*(.+)/i', $headers, $matches);
$sessionId = trim($matches[1] ?? '');

curl_close($ch);

Conversations Export API

Exporte las conversaciones de su chatbot en formato CSV o JSON a través de HTTP, filtradas por Período. Utilice esto para automatizar informes periódicos: extraer todas las conversaciones de un chatbot para un mes determinado, integrarlas en su propio análisis o archivarlas.

A diferencia de los endpoints de chat anteriores, este forma parte de la API del panel. No se autentica mediante dominio. Inicia sesión con las credenciales de su cuenta y reutiliza la cookie de sesión para la solicitud de exportación.

Authentication

POST https://webchatagent.com/api/auth/login

Envíe el correo y la contraseña de su panel como JSON. La respuesta establece una cookie de sesión; inclúyala en cada solicitud posterior. No existe una clave de API independiente.

FieldTypeRequiredDescription
emailstringSíSu correo de inicio de sesión en el panel.
passwordstringSíSu contraseña del panel.

Requisitos:

  • Disponible en todos los planes.
  • Los miembros del equipo necesitan el permiso Conversaciones.

Export Conversations

GET https://webchatagent.com/api/conversations/export

Query Parameters

ParameterTypeRequiredDescription
chatbotIdstring (UUID)NoLimita la exportación a un solo chatbot. Omítalo para exportar todos los chatbots a los que tenga acceso.
fromstring (YYYY-MM-DD)NoInicio del período, inclusive (límite de día UTC).
tostring (YYYY-MM-DD)NoFin del período, inclusive (límite de día UTC).
qstringNoFiltro de búsqueda. Coincide con ID de sesión, IP del cliente o contenido del mensaje.
formatstringNocsv (predeterminado) o json.

Una conversación está "dentro del rango" cuando tiene al menos un mensaje dentro del período. Las conversaciones coincidentes se exportan en su totalidad, incluidos los mensajes fuera del rango, de modo que una transcripción que cruce el límite de un mes nunca quede cortada.

Formato CSV: una fila por mensaje, con los metadatos de la conversación (nombre del chatbot, ID de sesión, recuento de mensajes, última actividad) repetidos en cada fila. Se devuelve como un archivo adjunto con BOM UTF-8, por lo que se abre correctamente en Excel.

Formato JSON: un objeto por conversación con sus mensajes anidados:

{
  "range": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" },
  "sessionsCount": 42,
  "messagesCount": 314,
  "sessions": [
    {
      "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatbotName": "Support Bot",
      "sessionId": "sess_abc123",
      "messagesCount": 6,
      "lastActivity": "2026-06-12T09:41:22.000Z",
      "lastLanguage": "de",
      "lastIp": "203.0.113.* (anon)",
      "messages": [
        {
          "role": "user",
          "content": "What are your business hours?",
          "sources": null,
          "browserLanguage": "de",
          "clientIp": "203.0.113.* (anon)",
          "referer": "https://example.com/contact",
          "createdAt": "2026-06-12T09:40:01.000Z"
        }
      ]
    }
  ]
}

Límites: una exportación está limitada a 50 000 mensajes. Las solicitudes mayores devuelven 413; reduzca el período o seleccione un solo chatbot. Las IP de los clientes se anonimizan en ambos formatos.

Tool Data Endpoints

Las demás herramientas del panel son legibles con la misma autenticación por cookie de sesión y admiten el mismo filtrado por fecha from / to (según la fecha de creación de cada registro, límites de día UTC, ambos inclusive). Solo devuelven JSON; todas ellas también aceptan omitir los parámetros de fecha para devolverlo todo.

EndpointReturnsTeam permission
GET /api/questions{ success, questions: [...] }Preguntas
GET /api/feedback{ success, data: [...], count }Comentarios
GET /api/leads{ success, leads: [...] }Leads
GET /api/bookings[...] (array simple), también acepta chatbotIdReservas

En el plan gratuito, estos endpoints ocultan los campos de contenido (***) en lugar de devolver 403.

# All leads collected in June
curl -b cookies.txt \
  "https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"

Example: Monthly Export with cURL

# 1. Log in once and store the session cookie
curl -c cookies.txt -X POST https://webchatagent.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'

# 2. Download all June conversations of one chatbot as CSV
curl -b cookies.txt -o conversations_june.csv \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30"

# Or as JSON for automated processing
curl -b cookies.txt \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30&format=json"

Error codes

StatusMeaning
401Sesión no iniciada o sesión caducada. Inicie sesión de nuevo.
403Plan gratuito, falta de permiso de Conversaciones o sin acceso al chatbot.
404El chatbotId indicado no existe en su cuenta.
413Coincidieron más de 50 000 mensajes. Reduzca el rango o elija un solo chatbot.