Chatbot WebSocket API (Live Chat)

WebSocket API

Используйте WebSocket API для онлайн-чата в реальном времени: мгновенная доставка сообщений, индикаторы набора текста, статус присутствия, автоматический перевод и управление жизненным циклом сессии. Один и тот же сокет обслуживает виджеты посетителей и панель оператора, поэтому вы можете создать собственную консоль оператора или управлять онлайн-чатом из своего бэкенда.

Endpoint

wss://webchatagent.com/api/livechat

Весь трафик передается в формате JSON. Вы отправляете события client:*, сервер возвращает события livechat:*. Каждое сообщение содержит поле type.

Создаете чат для посетителей на JavaScript? JavaScript SDK берет на себя подключение, повторное соединение, индикацию набора текста и завершение онлайн-чата: chat.liveChat().

Роли подключения

При подключении вы объявляете роль с помощью поля as:

RoleDescription
userПосетитель сайта в чате.
adminОператор, управляющий сессиями онлайн-чата.
widgetВстроенный виджет чата в режиме мониторинга (до перехвата диалога).

Роль определяет, какие данные вы получаете: клиенты admin получают полную историю сообщений и события только для администраторов; клиенты user получают только новые события в реальном времени (посетители загружают свою историю через REST endpoint истории, а не через сокет).

Краткий сценарий работы

  1. Откройте сокет и отправьте client:join, указав chatbotId, sessionId и as.
  2. Сервер ответит сообщением { "type": "livechat:status", "ok": true } для подтверждения подключения. Затем администраторы получают историю сообщений и текущий снимок livechat:status.
  3. Отправляйте client:message для публикации сообщений; получайте livechat:message для каждого нового сообщения.
  4. Отправляйте client:typing и получайте livechat:typing для отображения индикатора набора текста.
  5. Завершите сессию с помощью client:end или получите livechat:ended, когда другая сторона закроет чат.

Клиентские события (отправляемые вами)

client:join

Первое событие после подключения. Выполняет вход в комнату сессии (а для администраторов, и в комнату чат-бота).

{
  "type": "client:join",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "as": "user",
  "lang": "en",
  "translateEnabled": true,
  "retranslateBacklog": false
}
FieldTypeRequiredDescription
chatbotIdstringYesUUID вашего чат-бота. Для администратора, отслеживающего всех ботов, специальное значение "all" выполняет подключение без привязки к конкретной комнате.
sessionIdstringYesID сессии чата.
asstringYesuser, admin или widget.
langstringNoПредпочитаемый код языка (например, en, de, fr). Задает целевой язык перевода.
translateEnabledbooleanNoВключить автоматический перевод для этой сессии (по умолчанию: включено).
retranslateBacklogbooleanNoПовторно перевести существующие сообщения из истории на язык lang при подключении (admin).

client:message

Отправка сообщения в сессию. Сервер сохраняет его, переводит при включенной функции перевода и рассылает событие livechat:message.

{
  "type": "client:message",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "content": "I need help with my order",
  "lang": "en"
}
FieldTypeRequiredDescription
chatbotIdstringYesUUID вашего чат-бота.
sessionIdstringYesID сессии чата.
senderstringYesuser или admin.
contentstringYesТекст сообщения. Пустое или отсутствующее поле content игнорируется.
langstringNoПодсказка языка сообщения для перевода.

Первое сообщение от admin в сессии со статусом waiting переводит ее в активное состояние (статус → open) и автоматически добавляет системное уведомление о подключении оператора.

client:typing

Рассылка индикатора набора текста всем участникам сессии.

{
  "type": "client:typing",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "isTyping": true
}

client:meta

Обновление метаданных сессии (текущая страница), чтобы операторы видели, где находится посетитель.

{
  "type": "client:meta",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "pageUrl": "https://example.com/pricing",
  "pageTitle": "Pricing - Example",
  "referrer": "https://google.com",
  "browserLanguage": "en-US"
}

client:agent_takeover

Администратор инициирует перехват AI-сессии (переводит ее в статус open / human). Доступно только роли admin.

{
  "type": "client:agent_takeover",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID"
}

client:end

Завершение сессии.

{
  "type": "client:end",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "reason": "resolved"
}

client:widget_open / client:widget_close

Отправляется виджетом для регистрации или отмены регистрации активной сессии для отображения администратору (именно это заполняет список livechat:widget_sessions).

{
  "type": "client:widget_open",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "pageUrl": "https://example.com",
  "pageTitle": "Home",
  "browserLanguage": "en-US"
}

Серверные события (получаемые вами)

livechat:status

Две формы: простое подтверждение подключения { "type": "livechat:status", "ok": true } и снимок статуса сессии (ниже).

{
  "type": "livechat:status",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "status": "open",
  "mode": "human",
  "userName": "John",
  "userEmail": "john@example.com",
  "userLanguage": "en"
}
FieldTypeDescription
statusstringwaiting (оператор еще не подключился), open (оператор подключен) или closed.
modestringbot или human.
userNamestring | nullИмя посетителя, если оно было получено через Лиды.
userEmailstring | nullЭл. почта посетителя, если она была получена.
userLanguagestring | nullОпределенный язык посетителя.

livechat:message

Новое сообщение (или сообщение из истории).

{
  "type": "livechat:message",
  "id": 1024,
  "sessionId": "SESSION_ID",
  "sender": "admin",
  "content": "Hello! How can I help you today?",
  "country": "DE",
  "createdAt": "2025-01-15T10:30:00Z",
  "file": null,
  "audience": "admin",
  "historical": false
}
FieldTypeDescription
idnumberID сообщения (соответствует id в истории REST).
senderstringuser, admin или system.
contentstringТекст сообщения. Для клиентов admin с включенным переводом текст уже переведен на язык администратора.
countrystring | nullКод страны отправителя, если определен.
createdAtstringМетка времени в формате ISO 8601.
fileobject | nullМетаданные прикрепленного файла (uploadId, name, mimeType, size, url, isImage), если сообщение представляет собой загрузку.
audiencestring | nullЗначение "admin" для копии сообщения, предназначенной администратору. В копии для пользователя это поле отсутствует.
historicalbooleantrue для сообщений из истории, воспроизводимых при входе.

Системные сообщения: когда sender равен system, поле content содержит токен, который клиент должен локализовать, а не выводить напрямую: __agent_joined__, __livechat_ended__ или __livechat_timeout__.

livechat:typing

Индикатор набора текста от другого участника: { type, chatbotId, sessionId, sender, isTyping }.

livechat:presence

Статус онлайн/оффлайн посетителя в сессии: { type, chatbotId, sessionId, online } (boolean).

livechat:meta

Обновленные метаданные сессии (текущая страница, заголовок, реферер), только для роли admin.

livechat:ended

Сессия была закрыта.

{
  "type": "livechat:ended",
  "sessionId": "SESSION_ID",
  "reason": "admin_closed"
}

Поле reason принимает значения user_closed (посетитель завершил сессию через POST /api/livechats/end), admin_closed (завершено через сокет) или already_closed (вы подключились к сессии, которая уже была завершена).

Чат в режиме ожидания, к которому не подключился ни один оператор, закрывается сервером с помощью события livechat:status (status: "closed") без отправки livechat:ended. Обрабатывайте оба варианта как завершение онлайн-чата.

События только для администратора

EventPayloadPurpose
livechat:active_count{ chatbotId, count }Активные сессии (ожидание + открытые).
livechat:waiting_count{ chatbotId, count }Сессии в ожидании (значок для чатов без ответа).
livechat:new_request{ chatbotId, sessionId, status, mode, ... }Новый онлайн-чат ожидает оператора.
livechat:widget_sessions{ chatbotId, chatbotName, sessions }Текущий список активных сессий виджета.
livechat:notification{ chatbotId, sessionId, content, sender }Новое сообщение, пока оператор находится в другом разделе панели управления.

Автоматический перевод

Сокет может автоматически переводить сообщения между языками посетителя и оператора:

  • Подключитесь с параметром translateEnabled: true и укажите в lang ваш язык.
  • Сообщения от собеседника приходят уже переведенными на ваш lang. Каждый участник сохраняет исходный текст своих сообщений, а переведенная копия доставляется другой стороне.
  • Перевод выполняется через Azure OpenAI в ЕС, поэтому оператор может общаться с посетителем на любом языке без ручного перевода.

Пример: собственный клиент онлайн-чата

const ws = new WebSocket('wss://webchatagent.com/api/livechat');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'client:join',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    as: 'user',
    lang: 'en'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'livechat:status':
      // Join ack ({ ok: true }) or a session snapshot ({ status, mode, ... })
      if (data.ok) console.log('Joined');
      else console.log(`Status: ${data.status}, mode: ${data.mode}`);
      break;
    case 'livechat:message':
      if (data.sender === 'system') {
        // Localize tokens like __agent_joined__ / __livechat_ended__
        console.log('[system]', data.content);
      } else {
        console.log(`${data.sender}: ${data.content}`);
      }
      break;
    case 'livechat:typing':
      console.log(`${data.sender} is typing: ${data.isTyping}`);
      break;
    case 'livechat:ended':
      console.log(`Session ended: ${data.reason}`);
      ws.close();
      break;
  }
};

function sendMessage(text) {
  ws.send(JSON.stringify({
    type: 'client:message',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    sender: 'user',
    content: text,
    lang: 'en'
  }));
}

function sendTyping(isTyping) {
  ws.send(JSON.stringify({
    type: 'client:typing',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    sender: 'user',
    isTyping
  }));
}