Widget API

Браузерное API, которое использует виджет <pleiades-chat> . Эта страница нужна только для создания собственного клиента или отладки виджета. Все пути находятся под /v1/widget.

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

ЗаголовокКем используетсяЗначение
x-publishable-key: pk_...только POST /visitorsПубличный ключ канала.
x-visitor-tokenвсе остальные эндпоинтыТокен, возвращённый POST /visitors.
Originвсе (устанавливается браузером)Должен входить в список разрешённых origin'ов канала.
content-type: application/jsonPOST с телом

Порядок такой: один раз получите токен посетителя по ключу, затем отправляйте только токен. Токен хранится на сервере в виде хеша и имеет скользящий срок жизни (по умолчанию 24 часа, продлевается при каждом использовании). Запрос с отсутствующим, неизвестным или просроченным токеном получает 401; после этого клиент должен создать нового посетителя.

Ни одному из этих эндпоинтов не нужен транспортный HARNESS_API_KEY; этот ключ предназначен для Server API .

CORS

OPTIONS /v1/widget/* отвечает 204 со следующими заголовками, когда Origin принадлежит веб-каналу, и пустым 403 в остальных случаях:

ЗаголовокЗначение
access-control-allow-originOrigin запроса
access-control-allow-methodsGET, POST, OPTIONS
access-control-allow-headerscontent-type, x-visitor-token, x-publishable-key
access-control-max-age600

Остальные ответы содержат access-control-allow-origin: <Origin> и vary: Origin, когда origin известен. Если origin не разрешён для канала, сервер отвечает 403 без заголовков CORS, поэтому браузер сообщает о сетевой ошибке и скрывает причину.

Эндпоинты

POST /v1/widget/visitors

Создаёт анонимного посетителя.

curl -i -X POST https://agent.example.com/v1/widget/visitors \
  -H "Origin: https://shop.example" \
  -H "x-publishable-key: pk_your_channel_key"
sh

201:

{ "visitorToken": "…", "expiresAt": 1790000000000 }
json

expiresAt — Unix-время в миллисекундах.

POST /v1/widget/threads

Начинает разговор для посетителя.

curl -X POST https://agent.example.com/v1/widget/threads \
  -H "Origin: https://shop.example" -H "x-visitor-token: $TOKEN"
sh

201: { "threadId": "…" }.

GET /v1/widget/threads/:id/messages

Недавняя история посетителя в треде (по умолчанию последние 10 сообщений), сначала самые старые. 404, если тред не принадлежит посетителю.

200:

{
  "items": [
    { "id": "41", "role": "user", "content": "Find a double room", "createdAt": 1790000000000 },
    {
      "id": "42", "role": "assistant", "content": "Two rooms are free.", "createdAt": 1790000004000,
      "steps": [{ "id": "search_rooms", "phase": "done", "text": "Looking for rooms…" }]
    }
  ]
}
json

steps присутствует в ответе, в котором использовались инструменты.

POST /v1/widget/messages

Отправляет сообщение и передаёт ответ потоком NDJSON (см. Поток ).

Поле телаТипОбязательноПримечания
threadIdstringдаТред этого посетителя.
textstringдаНе более WIDGET_MAX_TEXT_CHARS (по умолчанию 2000), иначе 413.
pagestringнетpathname + search посетителя, не более 512 символов.
customerContextobjectнетПлоская карта строковых, числовых или булевых значений. Её JSON не должен превышать тот же лимит символов, что и text, иначе 413.
curl -N -X POST https://agent.example.com/v1/widget/messages \
  -H "Origin: https://shop.example" -H "x-visitor-token: $TOKEN" \
  -H "content-type: application/json" \
  -d '{"threadId":"'"$THREAD"'","text":"book a double room for Friday","page":"/rooms"}'
sh

POST /v1/widget/tools

Регистрирует каталог инструментов страницы для треда. Виджет вызывает его при открытии панели и снова при изменении каталога. См. Инструменты .

Поле телаТипПримечания
threadIdstringТред этого посетителя.
webmcpToolsarrayКаждый элемент: name (string), необязательный description (string), необязательный inputSchema { type: "object", properties?, required? }.

Сериализованный webmcpTools не должен превышать WIDGET_MAX_WEBMCP_TOOLS_CHARS (по умолчанию 20 000), иначе 413. Поля вне схемы отбрасываются. Пустой массив очищает каталог треда. Ответ: 204, без тела.

curl -X POST https://agent.example.com/v1/widget/tools \
  -H "Origin: https://shop.example" -H "x-visitor-token: $TOKEN" \
  -H "content-type: application/json" \
  -d '{"threadId":"'"$THREAD"'","webmcpTools":[{"name":"set_pizza_size","description":"Set the pizza size.","inputSchema":{"type":"object","properties":{"size":{"type":"string","enum":["small","medium","large"]}},"required":["size"]}}]}'
sh

POST /v1/widget/tool-results

Отвечает на строку tool_call и возобновляет запуск. Ответ — новый поток NDJSON с теми же типами строк.

Поле телаТипОбязательноПримечания
threadIdstringда
callIdstringдаcallId строки tool_call, на которую даётся ответ.
toolstringдаtool из этой же строки.
resultanyдаТо, что вернул инструмент. MCP {content:[{text}]}, строка или JSON; сохраняется его текст (4000 символов).
isErrorbooleanнетПо умолчанию false.
pagestringнетГде посетитель находится сейчас (инструмент мог выполнить переход).

Поток

POST /messages и POST /tool-results отвечают с content-type: application/x-ndjson: один JSON-объект на строку. Тело сжимается gzip (content-encoding: gzip), когда запрос отправляет accept-encoding: gzip.

typeПоляЗавершающий?
deltatextнет. Фрагмент текста ответа; дописывайте его.
stepid, phase (running, done, failed), textнет. Прогресс на языке посетителя. Более поздний step с тем же id заменяет предыдущий.
tool_calltool, arguments, callIdзавершает этот поток. Выполните инструмент в браузере и вызовите POST /tool-results.
doneelapsedMs; необязательные inputTokens, outputTokens, totalInputTokens, totalOutputTokensда. Цель достигнута.
errormessage; необязательные code, hintда.

error с code: "task_failed" означает, что сервер отработал, но сайт не смог выполнить задачу. hint — последний ответ инструмента самого сайта (не более 400 символов), обычно совет о том, что попробовать. error без кода — сбой на стороне сервера. Оборванное соединение никогда не приходит строкой; клиент замечает его сам.

Пример:

{"type":"step","id":"search_rooms","phase":"running","text":"Looking for rooms…"}
{"type":"tool_call","tool":"search_rooms","arguments":{"checkIn":"2026-11-06","checkOut":"2026-11-08","guests":2},"callId":"6f1c…"}
null

Клиент выполняет search_rooms, затем отправляет результат и читает следующий поток:

curl -N -X POST https://agent.example.com/v1/widget/tool-results \
  -H "Origin: https://shop.example" -H "x-visitor-token: $TOKEN" \
  -H "content-type: application/json" \
  -d '{"threadId":"'"$THREAD"'","callId":"6f1c…","tool":"search_rooms","result":{"content":[{"type":"text","text":"- r12: double, $90/night"}]}}'
sh
{"type":"step","id":"search_rooms","phase":"done","text":"Found rooms"}
{"type":"delta","text":"Room r12 is free."}
{"type":"done","elapsedMs":2310}
null

(Тексты шагов выше приведены для иллюстрации; реальные тексты зависят от инструмента и языка посетителя.)

Запуск может выдать несколько строк tool_call одну за другой, каждую в своём потоке, до done или error.

Статусы ошибок

Ответы с ошибками имеют пустое тело.

СтатусГдеЗначение
401все, кроме /visitorsОтсутствующий, неизвестный или просроченный x-visitor-token. Создайте нового посетителя.
401/visitorsНеизвестный publishable key.
403всеOrigin не разрешён, канал отключён, посетителю не разрешено (режим доступа или блокировка) или IP заблокирован.
404маршруты тредовТред не существует или принадлежит другому посетителю.
413/messages, /tools, любойТекст, customerContext или каталог превышают свой лимит; либо Content-Length превышает WIDGET_MAX_BODY_BYTES (по умолчанию 131072) на любом маршруте виджета.
422маршруты POSTТело не соответствует схеме (валидация Elysia).
429см. нижеОграничение частоты запросов.

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

Фиксированные окна, в памяти, отдельно для каждого экземпляра сервера. Значения по умолчанию; каждое задаётся переменной окружения alpha-orchestrator:

ЛимитПрименяется кПо умолчаниюПеременная
Сообщений на токен посетителя в минутуPOST /messages, POST /tools10WIDGET_MESSAGES_PER_MINUTE
Сообщений на IP клиента в минутуто же30WIDGET_IP_MESSAGES_PER_MINUTE
Результатов инструментов на токен посетителя в минутуPOST /tool-results120WIDGET_TOOL_RESULTS_PER_MINUTE
Тредов на токен посетителя в часPOST /threads30WIDGET_THREADS_PER_HOUR
Новых посетителей на IP клиента в часPOST /visitors20WIDGET_VISITORS_PER_HOUR_PER_IP

POST /tools учитывается в лимитах сообщений, а не в лимите результатов инструментов. Лимит результатов инструментов отдельный, потому что один запрос может породить много обращений к браузеру (очистка корзины из 12 строк — это 13).

IP клиента по умолчанию берётся из сокета (CLIENT_IP_SOURCE, по умолчанию socket). За прокси оператор выбирает другой источник и количество доверенных прокси-узлов через TRUSTED_PROXY_HOPS (по умолчанию 1).