Widget API

Бұл бет машиналық аудармамен жасалған және тексерілуде. Қателер болуы мүмкін - ағылшын нұсқасын қараңыз.

<pleiades-chat> виджеті қолданатын браузерге арналған API. Бұл бет тек өз клиентіңізді жасау немесе виджетті жөндеу үшін керек. Барлық жолдар /v1/widget астында.

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

ТақырыпКім қолданадыМағынасы
x-publishable-key: pk_...тек POST /visitorsАрнаның ашық кілті.
x-visitor-tokenқалған барлық эндпоинттерPOST /visitors қайтарған токен.
Originбарлығы (браузер орнатады)Арнаның рұқсат етілген origin-дерінің бірі болуы керек.
content-type: application/jsonденесі бар POST

Реттілік: кілтпен келуші токенін бір рет алыңыз, содан кейін тек токенді жіберіңіз. Токен серверде хэштелген күйде сақталады және жылжымалы өмір сүру мерзімі бар (әдепкі 24 сағат, әр қолданғанда ұзартылады). Токені жоқ, белгісіз немесе мерзімі өткен сұраныс 401 алады; сонда клиент жаңа келуші құруы керек.

Бұл эндпоинттердің ешқайсысына транспорттық HARNESS_API_KEY қажет емес; ол кілт server API үшін.

CORS

OPTIONS /v1/widget/* Origin веб-арнаға тиесілі болса, мына тақырыптармен 204 жауап береді, әйтпесе бос 403:

ТақырыпМәні
access-control-allow-originсұраныстың Origin мәні
access-control-allow-methodsGET, POST, OPTIONS
access-control-allow-headerscontent-type, x-visitor-token, x-publishable-key
access-control-max-age600

Басқа жауаптарда origin белгілі болғанда access-control-allow-origin: <Origin> және vary: Origin болады. Origin арна үшін рұқсат етілмегенде сервер CORS тақырыптарынсыз 403 жауап береді, сондықтан браузер желі қатесін хабарлайды және себебін жасырады.

Эндпоинттер

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 ретінде ағынмен береді ( Stream бөлімін қараңыз).

Дене өрісіТүріМіндеттіЕскертпелер
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иәЖауап берілетін tool_call жолының callId мәні.
toolstringиәСол жолдың tool мәні.
resultanyиәҚұрал қайтарған нәрсе. MCP {content:[{text}]}, жол немесе JSON; оның мәтіні сақталады (4000 таңба).
isErrorbooleanжоқӘдепкі false.
pagestringжоқКелушінің қазір тұрған жері (құрал навигация жасаған болуы мүмкін).

Stream

POST /messages және POST /tool-results content-type: application/x-ndjson жауабын береді: әр жолда бір JSON-объект. Сұраныс accept-encoding: gzip жіберсе, дене gzip-пен сығылады (content-encoding: gzip).

typeӨрістерТерминал ма?
deltatextжоқ. Жауап мәтінінің бөлігі; оны қосып отырыңыз.
stepid, phase (running, done, failed), textжоқ. Келушінің тіліндегі прогресс. Сол id-мен кейінгі step ертерегін ауыстырады.
tool_calltool, arguments, callIdосы ағынды аяқтайды. Құралды браузерде орындап, POST /tool-results шақырыңыз.
doneelapsedMs; міндетті емес inputTokens, outputTokens, totalInputTokens, totalOutputTokensиә. Мақсатқа жетті.
errormessage; міндетті емес code, hintиә.

code: "task_failed" бар error сервердің жұмыс істегенін, бірақ сайт тапсырманы орындай алмағанын білдіреді. 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

(Жоғарыдағы қадам мәтіндері көрнекілік үшін; нақты мәтіндер құралға және келушінің тіліне байланысты.)

Бір жұмыс done немесе error алдында бірнеше tool_call жолын бірінен соң бірін, әрқайсысын өз ағынында шығара алады.

Қате статустары

Қате жауаптарының денесі бос.

СтатусҚайдаМағынасы
401/visitors қоспағанда барлығыx-visitor-token жоқ, белгісіз немесе мерзімі өткен. Жаңа келуші құрыңыз.
401/visitorsАшық кілт белгісіз.
403барлығыOrigin рұқсат етілмеген, арна өшірілген, келушіге рұқсат жоқ (қолжетімділік режимі немесе бұғатталған) немесе IP бұғатталған.
404тред маршруттарыТред жоқ немесе басқа келушіге тиесілі.
413/messages, /tools, кез келгенМәтін, customerContext немесе каталог шегінен асты; немесе кез келген виджет маршрутында Content-Length WIDGET_MAX_BODY_BYTES мәнінен асты (әдепкі 131072).
422POST маршруттарыДене схемаға сәйкес емес (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).