Справочник по REST API для Chatbot

REST API

Отправляйте сообщения вашему чат-боту и получайте ответы, сгенерированные ИИ, по обычному протоколу HTTP. Используйте это для создания собственного интерфейса чата, мобильного приложения или автоматизации на бэкенде. Все эндпоинты обслуживаются с того же источника, что и скрипт вашего виджета (https://webchatagent.com).

Как устроен диалог

1. Отправьте POST с message пользователя и вашим chatbotId на /api/chat.
2. Прочитайте reply из тела JSON. Прочитайте заголовок ответа X-Chat-Session-Id, это ваш ID сессии.
3. Для следующего сообщения передайте тот же ID сессии в заголовке запроса X-Chat-Session-Id. Теперь сервер владеет контекстом диалога: историей сообщений, контекстом знаний на основе источников (Retrieval-Augmented Generation, RAG) и состоянием онлайн-чата.
4. Повторите процесс. Опустите этот заголовок в любой момент, когда хотите начать новый диалог.

Сервер отслеживает историю для каждой сессии, поэтому вы отправляете только последнее сообщение, а не всю стенограмму.

Аутентификация

API использует аутентификацию на основе доменов: здесь нет API ключа. Каждый запрос проверяется на соответствие настроенным для чат-бота Allowed Domains с помощью заголовков Origin/Referer запроса. Запрос с домена, которого нет в списке разрешенных, получает ошибку 403.

Для чат-ботов типа Командная вики с ИИ с защищенным доступом также передавайте заголовок X-Wiki-Auth с токеном аутентификации вики (значение вида wiki_auth_<subdomain>). Без него защищенные вики возвращают 403.

Отправка сообщения

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

Заголовки

Тело запроса

Пример запроса

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

Ответ

ID сессии возвращается в заголовке ответа X-Chat-Session-Id, а не в теле.

Когда управление перехватывает оператор-человек (mode: "human", status: "open"), поле reply может быть пустым, оператор отвечает отдельно. Пока идет ожидание подключения (waiting), поле reply содержит короткое уведомление вроде "A team member will join shortly."

Массив Sources

Каждый объект источника:

Пример ответа

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

Потоковая передача: Если для чат-бота включен стриминг, виджет получает ответ по токенам через Server-Sent Events. Описанный здесь обычный ответ JSON возвращается для стандартного запроса и является подходящей моделью для интеграций сервер-сервер и большинства кастомных интерфейсов.

История чата

Получите сохраненные сообщения сессии (например, чтобы восстановить диалог после перезагрузки страницы). История старше 30 дней удаляется согласно GDPR; для устаревшей сессии возвращается 410.

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

Параметры запроса

Ответ

Массив messages отсортирован от старых к новым. Поле sender принимает значения bot или user (это значение для отображения, а не сырая роль). Поле role содержит базовую роль user / assistant / system, а isAgent имеет значение true, когда сообщение assistant пришло от оператора-человека, а не от ИИ.

{
  "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 присутствует, только когда у сообщения есть источники.

Информация о сессии

Получите количество сообщений и последнюю активность для сессий, известных этому браузеру. Чтобы исключить утечку чатов других посетителей, вы должны передать ID сессий, которые у вас уже есть (например, из локального хранилища). Сессии без активности за последние 30 дней не возвращаются.

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

Параметры запроса

Ответ

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

Сброс истории сессии

Очистите контекст диалога в оперативной памяти для сессии, чтобы при следующем сообщении ИИ начал диалог заново (без предыдущих реплик). Это не удаляет сохраненные сообщения: conversation_messages являются бизнес-данными и остаются в базе данных (и в /api/chat/history).

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

Заголовки

Ответ

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

Обработка ошибок

Ошибки от /api/chat возвращают ту же структуру, что и обычный ответ: понятное пользователю сообщение HTML в поле reply и пустой массив sources. Код состояния HTTP передает фактический тип ошибки.

Тело ответа с ошибкой

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

Тело всегда представляет собой { reply, sources }, отдельной оболочки для ошибок нет. Выполняйте ветвление логики по коду состояния HTTP и показывайте reply пользователю, если хотите использовать готовое сообщение.

Ограничение частоты запросов

Превышение любого из них возвращает 429. Отдельно, при достижении ежемесячной квоты сообщений по тарифу также возвращается 429 (с сообщением "temporarily unavailable").

Примеры кода

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

API экспорта Беседы

Экспортируйте беседы вашего чат-бота в формате CSV или JSON по HTTP с фильтрацией по диапазону дат. Используйте это для автоматизации регулярной отчетности: выгружайте все беседы чат-бота за определенный месяц, передавайте их в свои системы анализа или архивируйте.

В отличие от эндпоинтов чата выше, это часть API Панель управления. Здесь нет аутентификации по домену. Вы входите с учетными данными своего аккаунта и повторно используете сессионный cookie для запроса на экспорт.

Аутентификация

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

Отправьте ваш Email и Пароль от Панель управления в формате JSON. В ответе устанавливается сессионный cookie, добавляйте его в каждый последующий запрос. Отдельного API ключа нет.

Требования:

• Платный Тариф. Эндпоинт экспорта возвращает 403 на Бесплатный тарифе.
• Члены команды должны иметь разрешение Беседы.

Экспорт Беседы

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

Параметры запроса

Беседа считается попавшей в диапазон, если в ней есть хотя бы одно Сообщение внутри этого диапазона. Подходящие беседы экспортируются полностью, включая сообщения вне диапазона, поэтому Стенограмма, переходящая границу месяца, никогда не обрезается.

Формат CSV: одна строка на одно Сообщение с метаданными беседы (Имя чат-бота, ID сессии, количество сообщений, Последняя активность), повторяющимися в каждой строке. Возвращается как вложение Файл с UTF-8 BOM, поэтому корректно открывается в Excel.

Формат JSON: один объект на каждую беседу с вложенными сообщениями:

{
  "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"
        }
      ]
    }
  ]
}

Ограничения: Экспорт ограничен 50 000 сообщений. Запросы большего объема возвращают 413, сузьте Период или выберите один Чат-бот. IP-адреса клиентов анонимизируются в обоих форматах.

Эндпоинты данных Инструменты

Остальные Инструменты Панель управления доступны для чтения с той же аутентификацией по сессионным cookie и поддерживают такую же фильтрацию по датам from / to (по дате создания каждой записи, границы суток по UTC, обе включительно). Они возвращают только JSON, а также принимают запросы без параметров даты для получения всех данных.

На Бесплатный тарифе эти эндпоинты скрывают поля содержимого (***) вместо возврата ошибки 403.

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

Пример: Ежемесячно Экспорт с помощью 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"

Коды ошибок