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иәӨзіңіздің сөйлесу идентификаторыңыз. Арна мен пайдаланушы бойынша бірегей; бірінші қолданғанда тред құрылады.
userIdstringиәСіздің жүйеңіздегі пайдаланушы идентификаторы, арна шегінде. Пайдаланушы бірінші қолданғанда құрылады.
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 (сұраныс accept-encoding: gzip жіберсе, gzip). Жол түрлері Widget API: Stream бөлімінде сипатталғандар: delta, step, done, error.

СтатусМағынасы
200Ағын басталды.
401Транспорттық кілт қате немесе жоқ.
403Пайдаланушыға рұқсат жоқ (бұғатталған, немесе арна whitelist режимінде және пайдаланушы whitelist-те жоқ, немесе арна өшірілген). Дене бос: модель ешқашан шақырылмайды.
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": "…" }. Белгісіз slug үшін 404 Unknown channel.

Келушіні идентификациялау

POST /v1/channels/:slug/identify: келуші сіздің сайтыңызға кіргеннен кейін, оның анонимді виджет сессиясын өз аккаунт идентификаторыңызбен байланыстырыңыз. Оны серверіңізден шақырыңыз.

  1. Бетте токенді оқыңыз: await document.querySelector("pleiades-chat").getVisitorToken().
  2. Оны бэкендіңізге жіберіңіз, ол identify-ді арнаның құпия кілтімен шақырады.
Дене өрісіТүріМіндеттіЕскертпелер
visitorTokenstringиәВиджеттен.
externalUserIdstring, бос емесиәСіздің аккаунт идентификаторыңыз.
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.
  • Аккаунт бар: анонимді пайдаланушының тредтері, хабарламалары және жұмыстары (run) бір транзакцияда оған көшеді, ал анонимді жол жойылады, merged: true. Екі жақтың бірінде болған бұғаттау біріктіруден кейін сақталады, whitelist-ке қосу да.
  • Дәл сол шақыруды қайталау ештеңені өзгертпейді.
СтатусМағынасы
401Құпия кілт қате, немесе арна веб-арна емес.
404Арна slug-ы белгісіз, немесе келуші токені белгісіз не мерзімі өткен (немесе басқа арнаның токені).
409Токен басқа аккаунтқа бұрыннан байланған.
422Дене схемаға сәйкес емес.