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

REST API

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

Используете JavaScript или TypeScript? JavaScript SDK (npm install webchatagent) оборачивает эти эндпоинты в типизированные функции, поддерживает стриминг и живой чат.

Как работает диалог

  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 ключа. Каждый запрос сверяется со списком Разрешенные домены, настроенным у чат-бота, по заголовкам 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.

Тело запроса

ПолеТипОбязательноОписание
messagestringДаСообщение пользователя. Максимум 700 символов. Не может быть пустым.
chatbotIdstring (UUID)ДаID вашего чат-бота из настроек бота.
pageUrlstringНетПолный URL страницы, на которой находится посетитель (window.location.href). Используется для поиска с учетом страницы; проверяется по вашим разрешенным доменам.
contextDataobjectНетПлоский контекст ключ-значение о сессии посетителя (не более 20 ключей, до 64 символов на ключ, строковые, числовые или логические значения до 500 символов). Добавляется в промпт для ИИ только для этого запроса, не сохраняется отдельной записью; ИИ обрабатывает эти значения как данные, а не инструкции, и может передавать их в аргументы инструментов и коннекторов API. См. Данные контекста сессии.

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

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

Ответ

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

ПолеТипОписание
replystringОтвет в формате Markdown. В конце может содержаться скрытый HTML комментарий <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> с предложенными следующими вопросами: отобразите label на кнопке, отправьте text при клике и удалите комментарий перед отображением.
sourcesarrayИсточники, на которых основан ответ (см. ниже). Пусто, если источники не использовались.
modestringРежим диалога: bot (отвечает ИИ) или human (подключился оператор). Отображается, когда это применимо.
statusstringСтатус живого чата: waiting, open или closed. Присутствует, только когда для сессии активен Живой чат.
aiGeneratedbooleantrue, если ответ сгенерирован ИИ. Отсутствует, когда диалог ведет оператор.
conversationTooLongbooleanДиалог достиг лимита по длине. Начните новую сессию.

Когда управление перехватил оператор (mode: "human", status: "open"), поле reply может быть пустым, так как оператор отвечает отдельно. В состоянии перехвата waiting поле ответа содержит короткое уведомление вроде "Сотрудник скоро присоединится".

Массив источников

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

ПолеТипОписание
typestringweb (страница сайта), product (структурированные данные товара) или fileSource (документ из подключенного хранилища файлов).
sourcestringДля web: URL страницы. Для product: идентификатор товара. Для fileSource: ID документа.
dataobjectТолько для 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ПоляЗначение
tokendataСледующая часть ответа. Добавьте ее. Текст может содержать незавершенную разметку Markdown и начало комментария с подсказками.
tool_callnameБот вызывает инструмент, например поиск товара.
errordataПроблема. Обычно следом идет done; если поток завершается без done, считайте data самой ошибкой.
doneте же поля, что и в ответе JSONИтоговый ответ. Замените полученный из потока текст на reply.

Сервер возвращает обычный JSON вместо потока, если стриминг выключен в настройках чат-бота, когда диалог ведет оператор, а также в случае ошибок. Проверяйте Content-Type ответа. Закрытие соединения останавливает генерацию.

История чата

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

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

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

ПараметрТипОбязательноОписание
chatbotIdstring (UUID)ДаID вашего чат-бота.
sessionIdstring (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

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

ПараметрТипОбязательноОписание
chatbotIdstring (UUID)ДаID вашего чат-бота.
sessionIdsstringДа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

Заголовки

HeaderRequiredDescription
X-Chat-Session-IdДаСессия, чью историю в оперативной памяти необходимо очистить.

Ответ

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

Error Handling

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

StatusMeaning
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

ScopeLimit
На сессию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 нет.

FieldTypeRequiredDescription
emailstringДаЭл. почта для входа в Панель управления.
passwordstringДаПароль от Панели управления.

Требования:

  • Доступно на любом тарифе.
  • Участникам команды требуется разрешение Беседы.

Export Conversations

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

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

ParameterTypeRequiredDescription
chatbotIdstring (UUID)НетОграничить экспорт одним чат-ботом. Пропустите, чтобы экспортировать все доступные вам чат-боты.
fromstring (YYYY-MM-DD)НетНачало диапазона дат включительно (граница суток по UTC).
tostring (YYYY-MM-DD)НетКонец диапазона дат включительно (граница суток по UTC).
qstringНетПоисковый фильтр. Ищет по ID сессии, IP-адресу клиента или содержимому сообщений.
formatstringНет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; все они также могут принимать запросы без параметров дат, возвращая все данные.

EndpointReturnsTeam permission
GET /api/questions{ success, questions: [...] }Questions
GET /api/feedback{ success, data: [...], count }Feedback
GET /api/leads{ success, leads: [...] }Leads
GET /api/bookings[...] (обычный массив), также принимает chatbotIdBookings

На бесплатном тарифе эти эндпоинты скрывают поля содержимого (***) вместо возврата ошибки 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"

Коды ошибок

StatusMeaning
401Вход не выполнен или сессия истекла. Выполните вход снова.
403Бесплатный тариф, отсутствует разрешение Беседы или нет доступа к чат-боту.
404Указанный chatbotId не существует в вашем аккаунте.
413Найдено более 50 000 сообщений. Сузьте диапазон или выберите один Chatbot.