Справочник REST API для Chatbot
REST API
Отправляйте сообщения вашему чат-боту и получайте ответы от ИИ по обычному HTTP. Используйте это для создания собственного интерфейса чата, мобильного приложения или автоматизации на бэкенде. Все эндпоинты обслуживаются с того же источника, что и скрипт вашего виджета (https://webchatagent.com).
Используете JavaScript или TypeScript? JavaScript SDK (
npm install webchatagent) оборачивает эти эндпоинты в типизированные функции, поддерживает стриминг и живой чат.
Как работает диалог
- Отправьте POST с
messageпользователя и вашимchatbotIdна/api/chat. - Прочитайте
replyиз тела JSON. Прочитайте заголовок ответаX-Chat-Session-Id, это ID вашей сессии. - Для следующего сообщения отправьте тот же ID сессии в заголовке запроса
X-Chat-Session-Id. Теперь сервер владеет контекстом диалога: историей сообщений, контекстом знаний на основе источников (Retrieval-Augmented Generation, RAG) и состоянием живого чата. - Повторяйте процесс. Не передавайте заголовок, если хотите начать новый диалог.
Сервер отслеживает историю для каждой сессии, поэтому вы отправляете только последнее сообщение, а не всю стенограмму.
Аутентификация
API использует аутентификацию на основе доменов: здесь нет API ключа. Каждый запрос сверяется со списком Разрешенные домены, настроенным у чат-бота, по заголовкам Origin/Referer. Запрос с неразрешенного домена возвращает 403.
Для чат-ботов Командная вики с ИИ с защищенным доступом также отправляйте заголовок X-Wiki-Auth с токеном аутентификации вики (значение вида wiki_auth_<subdomain>). Без него защищенные вики возвращают 403.
Отправка сообщения
POST https://webchatagent.com/api/chat
Заголовки
| Заголовок | Обязательно | Описание |
|---|---|---|
Content-Type | Да | Должен быть application/json. |
X-Chat-Session-Id | Нет | ID сессии (UUID) для непрерывности диалога. Не указывайте в первом запросе; заголовок ответа вернет новый ID. Вы также можете сгенерировать случайный UUID самостоятельно. Любое значение, не являющееся UUID, заменяется новой сессией. |
Accept | Нет | text/event-stream для получения ответа в виде потока (см. Стриминг). |
Accept-Language | Нет | Предпочтительный язык ответа, например de. |
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
message | string | Да | Сообщение пользователя. Максимум 700 символов. Не может быть пустым. |
chatbotId | string (UUID) | Да | ID вашего чат-бота из настроек бота. |
pageUrl | string | Нет | Полный URL страницы, на которой находится посетитель (window.location.href). Используется для поиска с учетом страницы; проверяется по вашим разрешенным доменам. |
contextData | object | Нет | Плоский контекст ключ-значение о сессии посетителя (не более 20 ключей, до 64 символов на ключ, строковые, числовые или логические значения до 500 символов). Добавляется в промпт для ИИ только для этого запроса, не сохраняется отдельной записью; ИИ обрабатывает эти значения как данные, а не инструкции, и может передавать их в аргументы инструментов и коннекторов API. См. Данные контекста сессии. |
Пример запроса
{
"message": "What are your business hours?",
"chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Ответ
ID сессии возвращается в заголовке ответа X-Chat-Session-Id, а не в теле.
| Поле | Тип | Описание |
|---|---|---|
reply | string | Ответ в формате Markdown. В конце может содержаться скрытый HTML комментарий <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> с предложенными следующими вопросами: отобразите label на кнопке, отправьте text при клике и удалите комментарий перед отображением. |
sources | array | Источники, на которых основан ответ (см. ниже). Пусто, если источники не использовались. |
mode | string | Режим диалога: bot (отвечает ИИ) или human (подключился оператор). Отображается, когда это применимо. |
status | string | Статус живого чата: waiting, open или closed. Присутствует, только когда для сессии активен Живой чат. |
aiGenerated | boolean | true, если ответ сгенерирован ИИ. Отсутствует, когда диалог ведет оператор. |
conversationTooLong | boolean | Диалог достиг лимита по длине. Начните новую сессию. |
Когда управление перехватил оператор (mode: "human", status: "open"), поле reply может быть пустым, так как оператор отвечает отдельно. В состоянии перехвата waiting поле ответа содержит короткое уведомление вроде "Сотрудник скоро присоединится".
Массив источников
Каждый объект источника:
| Поле | Тип | Описание |
|---|---|---|
type | string | web (страница сайта), product (структурированные данные товара) или fileSource (документ из подключенного хранилища файлов). |
source | string | Для web: URL страницы. Для product: идентификатор товара. Для fileSource: ID документа. |
data | object | Только для product. Содержит id, dataType, format, data и sourceUrl. |
Пример ответа
{
"reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
"sources": [
{
"type": "web",
"source": "https://example.com/contact"
}
],
"mode": "bot"
}
Стриминг
Отправьте Accept: text/event-stream, чтобы получать ответ по мере его генерации. Если у чат-бота включен стриминг, ответом будет поток событий Server-Sent Events, каждое из которых представляет собой одну строку data: с объектом JSON, разделенных пустой строкой:
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}
type | Поля | Значение |
|---|---|---|
token | data | Следующая часть ответа. Добавьте ее. Текст может содержать незавершенную разметку Markdown и начало комментария с подсказками. |
tool_call | name | Бот вызывает инструмент, например поиск товара. |
error | data | Проблема. Обычно следом идет done; если поток завершается без done, считайте data самой ошибкой. |
done | те же поля, что и в ответе JSON | Итоговый ответ. Замените полученный из потока текст на reply. |
Сервер возвращает обычный JSON вместо потока, если стриминг выключен в настройках чат-бота, когда диалог ведет оператор, а также в случае ошибок. Проверяйте Content-Type ответа. Закрытие соединения останавливает генерацию.
История чата
Получение сохраненных сообщений сессии (например, чтобы восстановить диалог после перезагрузки страницы). История старше 30 дней удаляется в соответствии с GDPR; запрос по истекшей сессии возвращает 410.
GET https://webchatagent.com/api/chat/history
Параметры запроса
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
chatbotId | string (UUID) | Да | ID вашего чат-бота. |
sessionId | string (UUID) | Да | Сессия, историю которой вы запрашиваете. |
Ответ
Массив 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
Параметры запроса
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
chatbotId | string (UUID) | Да | ID вашего чат-бота. |
sessionIds | string | Да | UUID сессий через запятую (не более 5; лишние игнорируются). |
Ответ
{
"sessions": [
{
"sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"messageCount": 12,
"lastActivity": "2025-01-15T10:35:00Z"
}
]
}
Reset Session History
Очистите контекст беседы в оперативной памяти для сессии, чтобы следующее сообщение запустило ИИ с чистого листа (без предыдущих реплик). Это не удаляет сохраненные сообщения: conversation_messages являются бизнес-данными и остаются в базе данных (а также в /api/chat/history).
DELETE https://webchatagent.com/api/chat/session
Заголовки
| Header | Required | Description |
|---|---|---|
X-Chat-Session-Id | Да | Сессия, чью историю в оперативной памяти необходимо очистить. |
Ответ
{ "success": true, "message": "Chat session cleared." }
Error Handling
Большинство ошибок из /api/chat возвращают ту же структуру, что и обычный ответ: понятное пользователю HTML-сообщение в reply и пустой массив sources. Фактический тип ошибки определяется кодом статуса HTTP.
| Status | Meaning |
|---|---|
400 | Неверное тело запроса, пропущено поле, пустое сообщение или сообщение длиннее 700 символов. |
403 | Домен не разрешен, сбой аутентификации в wiki или действует ограничение тарифа. |
404 | Чат-бот не найден. |
429 | Превышен лимит запросов или исчерпана ежемесячная квота сообщений. |
502 | Провайдер ИИ (LLM) вернул ошибку. |
Тело ответа с ошибкой
{
"reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
"sources": []
}
Некорректные запросы (400), ограничение частоты запросов (429) и заблокированные IP-адреса (403) возвращают другое тело: { "error": true, "statusCode": 429, "message": "..." }. Сначала проверяйте код статуса HTTP, а затем отображайте пользователю reply или message.
Rate Limiting
| Scope | Limit |
|---|---|
| На сессию | 10 запросов в минуту |
| На IP-адрес | 15 запросов в минуту |
| На сессию и на IP-адрес | не менее 1 секунды между двумя запросами |
Превышение любого из них возвращает 429. Отдельно, достижение ежемесячной квоты сообщений по тарифу также возвращает 429 (с сообщением о временной недоступности).
Примеры кода
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
Экспортируйте беседы вашего чат-бота в формате CSV или JSON по HTTP с фильтрацией по диапазону дат. Используйте это для автоматизации периодической отчетности: выгружайте все беседы чат-бота за определенный месяц, передавайте их в собственные системы аналитики или сохраняйте в архив.
В отличие от эндпоинтов чата выше, этот метод входит в API Панели управления. Аутентификация по домену здесь не применяется. Вы выполняете вход с учетными данными своего аккаунта и повторно используете сессионную cookie для запроса на экспорт.
Authentication
POST https://webchatagent.com/api/auth/login
Отправьте адрес эл. почты и пароль от Панели управления в формате JSON. Ответ устанавливает сессионную cookie; передавайте ее в каждом последующем запросе. Отдельного ключа API нет.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Да | Эл. почта для входа в Панель управления. |
password | string | Да | Пароль от Панели управления. |
Требования:
- Доступно на любом тарифе.
- Участникам команды требуется разрешение Беседы.
Export Conversations
GET https://webchatagent.com/api/conversations/export
Параметры запроса
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | Нет | Ограничить экспорт одним чат-ботом. Пропустите, чтобы экспортировать все доступные вам чат-боты. |
from | string (YYYY-MM-DD) | Нет | Начало диапазона дат включительно (граница суток по UTC). |
to | string (YYYY-MM-DD) | Нет | Конец диапазона дат включительно (граница суток по UTC). |
q | string | Нет | Поисковый фильтр. Ищет по ID сессии, IP-адресу клиента или содержимому сообщений. |
format | string | Нет | csv (по умолчанию) или json. |
Беседа считается входящей в диапазон, если в ней есть хотя бы одно сообщение внутри этого диапазона. Подходящие беседы экспортируются целиком, включая сообщения вне указанного периода, поэтому стенограмма, переходящая через границу месяца, никогда не обрезается.
Формат 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; сузьте диапазон дат или выберите один Chatbot. В обоих форматах IP-адреса клиентов анонимизируются.
Tool Data Endpoints
Остальные инструменты Панели управления доступны для чтения с той же аутентификацией по сессионной cookie и поддерживают такую же фильтрацию по датам from / to (по дате создания каждой записи, границы суток по UTC, обе включительно). Они возвращают только JSON; все они также могут принимать запросы без параметров дат, возвращая все данные.
| Endpoint | Returns | Team permission |
|---|---|---|
GET /api/questions | { success, questions: [...] } | Questions |
GET /api/feedback | { success, data: [...], count } | Feedback |
GET /api/leads | { success, leads: [...] } | Leads |
GET /api/bookings | [...] (обычный массив), также принимает chatbotId | Bookings |
На бесплатном тарифе эти эндпоинты скрывают поля содержимого (***) вместо возврата ошибки 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"
Коды ошибок
| Status | Meaning |
|---|---|
401 | Вход не выполнен или сессия истекла. Выполните вход снова. |
403 | Бесплатный тариф, отсутствует разрешение Беседы или нет доступа к чат-боту. |
404 | Указанный chatbotId не существует в вашем аккаунте. |
413 | Найдено более 50 000 сообщений. Сузьте диапазон или выберите один Chatbot. |
