Server API

Эндпоинты для вашего бэкенда, ботов и скриптов. Они отделены от браузерного Widget API : браузер их никогда не вызывает.

Интерактивный справочник

Все маршруты описаны в Swagger (OpenAPI), читать его можно без ключа:

  • Публично: albedo.shalotts.site/swagger , документ OpenAPI лежит на /swagger/json. В нём перечислены все маршруты оркестратора, но снаружи на публичном адресе отвечают не все (админские и транспортные там закрыты): их вызывайте на своём экземпляре.
  • Локально: оркестратор слушает порт 3000 (PORT), в docker compose он привязан к 127.0.0.1: localhost:3000//swagger . При запуске из исходников (bun --cwd apps/alpha-orchestrator run dev) адрес тот же. У admin API свой справочник: localhost:3003//api/docs .

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

ЭндпоинтУчётные данные
POST /v1/messages, POST /v1/accessAuthorization: Bearer <HARNESS_API_KEY>: транспортный секрет, настроенный в alpha-orchestrator (то же значение, что в telegram-bot и CLI).
POST /v1/channels/:slug/identifyAuthorization: Bearer sk_...: секретный ключ канала. Транспортный ключ здесь не принимается и не нужен.

Транспортный запрос с отсутствующим или неверным ключом получает 401 с телом Unauthorized. /health и /swagger открыты; интерактивный справочник API находится на /swagger.

Никогда не помещайте HARNESS_API_KEY или ключ sk_ на страницу или в клиентский бандл.

Отправка сообщения

POST /v1/messages: транспорт (чат-бот, CLI, ваш бэкенд) отправляет сообщение пользователя и читает ответ в виде NDJSON.

Поле телаТипОбязательноПримечания
threadIdstringдаВаш собственный id разговора. Уникален в пределах канала и пользователя; первое использование создаёт тред.
userIdstringдаId пользователя в вашей системе, в пределах канала. Пользователь создаётся при первом использовании.
textstringда
channelstringнетSlug канала. По умолчанию cli.
displayNamestringнетСохраняется вместе с пользователем.
curl -N -X POST http://localhost:3000/v1/messages \
  -H "Authorization: Bearer $HARNESS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"channel":"support-bot","threadId":"chat-17","userId":"u-42","displayName":"Aida","text":"What can you do?"}'
sh

Ответ имеет тип application/x-ndjson (gzip, если запрос отправляет accept-encoding: gzip). Типы строк те же, что описаны в Widget API: Поток : delta, step, done, error.

СтатусЗначение
200Поток начат.
401Неверный или отсутствующий транспортный ключ.
403Пользователю не разрешено (он заблокирован, либо канал в режиме белого списка, а пользователя в нём нет, либо канал отключён). Пустое тело: модель не вызывается.
404Unknown channel.
422Тело не соответствует схеме.

Проверка доступа

POST /v1/access: спросите, может ли отправитель общаться с ботом, прежде чем отвечать ему. Пользователь создаётся при первом использовании.

Поле телаТипОбязательно
channelstringда
externalUserIdstringда
displayNamestringнет
curl -X POST http://localhost:3000/v1/access \
  -H "Authorization: Bearer $HARNESS_API_KEY" -H "content-type: application/json" \
  -d '{"channel":"support-bot","externalUserId":"u-42"}'
sh

200: { "allowed": true, "userId": "…" }. 404 Unknown channel для неизвестного slug.

Идентификация посетителя

POST /v1/channels/:slug/identify: после того как посетитель вошёл на вашем сайте, свяжите его анонимную сессию виджета с вашим собственным id аккаунта. Вызывайте это с вашего сервера.

  1. На странице прочитайте токен: await document.querySelector("pleiades-chat").getVisitorToken().
  2. Отправьте его на ваш бэкенд, который вызывает identify с секретным ключом канала.
Поле телаТипОбязательноПримечания
visitorTokenstringдаИз виджета.
externalUserIdstring, непустаядаId вашего аккаунта.
curl -X POST https://agent.example.com/v1/channels/my-shop/identify \
  -H "Authorization: Bearer $CHANNEL_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{"visitorToken":"…","externalUserId":"account-9001"}'
sh

200: { "userId": "…", "merged": false }.

  • Аккаунта с таким externalUserId в канале ещё нет: анонимный пользователь повышается на месте, merged: false.
  • Аккаунт существует: треды, сообщения и запуски анонимного пользователя переносятся на него в одной транзакции, а анонимная запись удаляется, merged: true. Блокировка с любой из сторон сохраняется при слиянии, как и включение в белый список.
  • Повтор того же вызова ничего не меняет.
СтатусЗначение
401Неверный секретный ключ либо канал не является веб-каналом.
404Неизвестный slug канала, либо неизвестный или просроченный токен посетителя (или токен другого канала).
409Токен уже привязан к другому аккаунту.
422Тело не соответствует схеме.