WebSocket API приложения

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

Подготовка

Войдите в приложение и получите действующий токен доступа. Для работы в контексте проекта подготовьте его UUID и явное разрешение доступа для этого пользователя к проекту. WebSocket проверяет разрешение при передаче X-Project-Id. Для подписки на задачу нужен её job_id. Используйте адрес API вашей установки: wss для HTTPS и ws для доверенной локальной HTTP-среды.

Граница аутентификации

Для чата и статусов задач клиент передаёт токен в HTTP-заголовке при открытии соединения:

Authorization: Bearer <access-token>

Передавайте токен предусмотренным для маршрута способом. Если в URL есть непустой параметр token, сервер отклоняет запрос со статусом 403 до открытия WebSocket. Причина отказа — Query token transport is not allowed.

Для доступа в контексте проекта добавьте его постоянный идентификатор:

X-Project-Id: <project-uuid>

Сервер проверяет текущее состояние пользователя, отзыв токена, доступ к проекту, владение задачей там, где оно требуется, а также квоты соединений и сообщений. Клиент с loopback-адреса может работать без токена только при явно включённом локальном режиме и локальных адресах клиента и запрошенного хоста.

Чат и статусы задач подключайте через клиент с поддержкой заголовков или аутентифицированный шлюз того же источника (same-origin gateway). Маршрут уведомлений поддерживает браузерный WebSocket: после открытия соединения передайте токен первым сообщением в течение 5 секунд:

{"token": "<access-token>"}

После проверки токена и доступа сервер отправляет connected. Затем клиент может отправлять ping и получать уведомления. При превышении времени ожидания сервер закрывает соединение кодом 1008 с причиной Auth timeout.

События дашборда описаны в WebSocket API дашборда.

Маршруты

Маршрут задачи сначала проверяет право подписки. Неизвестная задача или задача вне области пользователя вызывает Job subscription denied и закрытие с кодом 1008. После разрешения подписки сервер читает состояние задачи; если это чтение не нашло задачу, он отправляет Job not found и закрывает соединение с кодом 4004.

Формат сообщения

Каждое сообщение приложения — JSON следующей формы:

{
  "type": "chat.query",
  "payload": {},
  "timestamp": "2026-08-24T00:00:00Z",
  "request_id": "optional-correlation-id"
}

Модель требует type. Если payload не передан, он равен {}; timestamp получает текущее время. Для chat.query нужен payload.query. Поле request_id необязательно; сохраняйте его для сопоставления сообщений одного потокового ответа.

Актуальные типы сообщений

Не каждый тип создаётся на каждом маршруте. Клиент должен игнорировать нерелевантные для текущего процесса известные сообщения и не считать неизвестное сообщение подтверждением успеха.

Запрос чата

Отправляйте chat.query в маршрут чата:

{
  "type": "chat.query",
  "payload": {
    "query": "Покажи вызывающие символы",
    "session_id": "optional-session",
    "scenario_id": "optional-scenario",
    "language": "ru"
  },
  "request_id": "req-123"
}

Значения optional-session и optional-scenario обозначают ваши идентификаторы сессии и сценария. Оба поля необязательны; опустите их, если запрос не задаёт сессию или сценарий явно.

Обработчик чата отправляет chat.scenario при выборе сценария, chat.chunk для фрагментов ответа и chat.done при завершении. Соберите ответ из фрагментов и сопоставьте их по request_id. При ошибке обработки сервер отправляет error с тем же идентификатором запроса.

Статус задачи

Подключайтесь к маршруту задачи, принадлежащей аутентифицированному пользователю. Сервер передаёт job.started с текущим состоянием, а для завершённой задачи — job.completed или job.failed. Получайте сохранённое состояние через HTTP/REST, а оперативные уведомления — через WebSocket.

Уведомления

Маршрут уведомлений предназначен преимущественно для получения данных. После аутентификации клиент отправляет ping. Поле payload уведомления может включать title, message, level и action_url. Перед переходом проверяйте action_url по навигационной политике приложения.

Подключение к уведомлениям

В этом примере сервисный клиент передаёт заголовок X-Project-Id, чтобы подписаться в контексте проекта. Пример использует Node.js и пакет ws. В каталоге клиентского проекта установите зависимость npm install ws, сохраните код в notifications.mjs и запустите node notifications.mjs. Перед запуском задайте CODEGRAPH_ACCESS_TOKEN, CODEGRAPH_PROJECT_ID и CODEGRAPH_WS_URL через одобренный канал конфигурации. Последняя переменная содержит полный адрес маршрута уведомлений. Не передавайте секрет как аргумент командной строки. Клиент отправляет токен первым сообщением, ждёт connected, затем отправляет ping. В консоли появится pong. При закрытии соединения клиент выведет код и причину: 1008 project_access_denied означает, что нужно проверить разрешение доступа к проекту. Для остановки клиента нажмите Ctrl+C.

import WebSocket from "ws";

for (const name of ["CODEGRAPH_ACCESS_TOKEN", "CODEGRAPH_PROJECT_ID", "CODEGRAPH_WS_URL"]) {
  if (!process.env[name]) throw new Error("Missing " + name);
}

const socket = new WebSocket(
  process.env.CODEGRAPH_WS_URL,
  {
    headers: {
      "X-Project-Id": process.env.CODEGRAPH_PROJECT_ID
    }
  }
);

socket.on("message", (raw) => {
  const message = JSON.parse(raw.toString());
  if (message.type === "notification") {
    console.log(message.payload);
  } else if (message.type === "connected") {
    socket.send(JSON.stringify({ type: "ping", payload: {} }));
  } else if (message.type === "pong") {
    console.log("pong");
  }
});

socket.on("open", () => {
  socket.send(JSON.stringify({ token: process.env.CODEGRAPH_ACCESS_TOKEN }));
});

socket.on("close", (code, reason) => {
  console.error("WebSocket closed:", code, reason.toString());
});

socket.on("error", () => {
  console.error("WebSocket connection failed; check the API address and server availability.");
});

Не записывайте токен и полный Authorization header в логи.

Коды закрытия и восстановление

Отказ до открытия WebSocket возвращает HTTP 403. Таблица описывает коды политики сервера; клиент получает WebSocket-код закрытия после успешного открытия соединения.

После временного разрыва увеличивайте задержку между повторными подключениями до заданного предела и добавляйте случайный разброс. После 4001 обновите токен. Не повторяйте 1008 автоматически, пока причина отказа не устранена.

WebSocket-маршруты не входят в набор REST-операций OpenAPI.