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).

Cómo funciona una conversación

1. Envía un POST con el message del usuario y tu chatbotId a /api/chat.
2. Lee la reply en el cuerpo JSON. Lee el encabezado 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 el encabezado de solicitud X-Chat-Session-Id. El servidor dispondrá ahora del contexto de la conversación: historial de mensajes, contexto de conocimiento basado en fuentes (Retrieval-Augmented Generation, RAG) y el estado del chat en vivo.
4. Repite el proceso. Omite el encabezado cada vez que quieras iniciar una nueva conversación.

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 verifica comparándola con los Allowed Domains configurados en el chatbot mediante los encabezados Origin/Referer de la solicitud. Una solicitud procedente de un dominio no permitido recibe un 403.

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

Enviar un mensaje

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

Encabezados

Cuerpo de la Solicitud

Ejemplo de solicitud

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

Respuesta

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

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

Array de fuentes

Cada objeto de fuente:

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: Si un chatbot tiene habilitado el streaming, el widget recibe la respuesta token a token a través de Server-Sent Events. La respuesta en JSON estándar documentada aquí es la que se obtiene para una solicitud habitual y representa el modelo adecuado para integraciones entre servidores y la mayoría de las interfaces de usuario personalizadas.

Historial de chat

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

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

Parámetros de consulta

Respuesta

messages se ordena del más antiguo al más reciente. sender es bot o user (es un valor para visualización, no el rol en bruto). role es el rol subyacente user / assistant / system, y isAgent es true cuando un mensaje de tipo 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 está presente cuando un 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 enviar los ID de sesión que ya posees (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

Respuesta

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

Restablecer historial de sesión

Borra el contexto de conversación en memoria de una sesión para que el siguiente mensaje inicie la IA desde cero (sin turnos anteriores). Esto no elimina los mensajes almacenados: 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

Encabezados

Respuesta

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

Gestión de errores

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

Cuerpo de respuesta de error

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

El cuerpo siempre es { reply, sources }, no existe una estructura de error independiente. Aplica la lógica según el código de estado HTTP y muestra reply al usuario si deseas un mensaje predefinido.

Límite de tasa

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

Ejemplos de código

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 como CSV o JSON a través de HTTP, filtradas por período. Utilice esto para automatizar informes periódicos: obtenga todas las conversaciones de un chatbot para un mes determinado, utilícelas en sus propios análisis o archívelas.

A diferencia de los endpoints de chat anteriores, este forma parte de la API del panel. No requiere autenticación por dominio. Inicie sesión con las credenciales de su cuenta y reutilice la cookie de sesión para la solicitud de exportación.

Autenticación

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

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

Requisitos:

• Un plan de pago. El endpoint de exportación devuelve 403 en el plan gratuito.
• Los miembros del equipo necesitan el permiso Conversaciones.

Exportar conversaciones

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

Parámetros de consulta

Una conversación está "dentro del rango" cuando tiene al menos un mensaje dentro del período. Las conversaciones coincidentes se exportan completas, incluidos los mensajes fuera del rango, para 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 UTF-8 BOM para que se abra 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 tiene un límite de 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.

Endpoints de datos de herramientas

Las demás herramientas del panel se pueden consultar mediante la misma autenticación por cookie de sesión y admiten el mismo filtrado de fechas from / to (según la fecha de creación de cada registro, límites de día UTC, ambos inclusivos). Solo devuelven JSON; todos ellos también aceptan solicitudes sin parámetros de fecha para devolverlo todo.

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"

Ejemplo: exportación mensual con 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"

Códigos de error