POST /message: чат через HTTP

Для розробників, у коді: синхронний ендпоінт чату для власної інтеграції — поля запиту, відповідь із джерелами, діями і підказками, і кожен статус, який він повертає.

POST /message відповідає на одне повідомлення відвідувача і повертає всю відповідь одразу. Віджет натомість використовує WebSocket (WebSocket); /message — для серверної інтеграції чи фронтенду, якому не потрібне потокове передавання. Дії на сторінці, яким потрібен обмін із браузером посеред ходу, тут недоступні.

POST /message
X-Widget-Key: wk_…
Content-Type: application/json

{ "agent_code": "default", "widget_code": "default",
  "message": "Яка у вас політика повернення?",
  "conversation_id": null, "page_url": "https://shop.example/cart", "page_lang": "uk" }

Запит

Поле	Тип	Обов’язкове	Сенс
`agent_code`	рядок	так	помічник у межах сайту ключа
`message`	рядок, непорожній	так	текст відвідувача
`conversation_id`	UUID або null		продовжити розмову; пропустіть, щоб почати нову
`widget_code`	рядок		який віджет говорить (кілька можуть ділити одного помічника)
`page_url`	рядок		сторінка, на якій відвідувач; зіставляється з маршрутами екранів додатка
`page_lang`	рядок		`<html lang>` — запасна мова відповіді, коли мову повідомлення не визначити
`session_id`	рядок		id сесії перегляду, для аналітики
`external_user_id`	рядок		id з вашого боку; не автентифікація
`user_token`	рядок		токен користувача, що увійшов, передається інструментам як `{{user}}`; не зберігається; довший за 8 192 символи ігнорується
`spoken`	boolean		відповідь читатимуть уголос — коротко, і хід коштує голосову надбавку
`page_route`, `page_params`	рядок, об’єкт		оголошений екран (`/orders/{id}`, `{ id }`), коли URL його не називає; маршрут ≤ 255, ≤ 20 параметрів
`visitor`	об’єкт		контекст приходу, читається лише на кадрі, що створює розмову: `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `browser_language`, `timezone`, `widget_language` — кожне рядок, обрізаний до 2 000
`page`	об’єкт		підказка дій на сторінці: `readable`, `actionable`, `counts`, `submit_policy` — має сенс лише на сокеті
`suppress_teaser`	boolean		застаріле; пропустити маршрутизацію тизера цього ходу

Відповідь

{
  "conversation_id": "…",
  "answer": "Повернути будь-який товар можна протягом 30 днів …",
  "sources": [
    { "source_id": "…", "title": "Повернення", "description": "…", "url": "…", "score": 0.82 }
  ],
  "actions": [],
  "nav_suggestions": [
    { "type": "navigate", "url": "…", "label": "Open: Повернення", "source_id": "…" }
  ],
  "metadata": {
    "tags": [],
    "language": "uk",
    "chunks_retrieved": 3,
    "top_score": 0.82,
    "search_calls": 1,
    "had_insufficient_context": false,
    "model": "claude-haiku-5-5"
  }
}

Поле	Сенс
`answer`	Markdown; віджет малює безпечну підмножину
`sources[]`	цитати: назва й опис сторінки (її власні метадані), URL, оцінка
`actions[]`	що хід просить хоста зробити — Дії. `navigate` тут виконується зараз; з `confirm: true` — це питання, що чекає на «так»
`nav_suggestions[]`	щонайбільше одна сторінка, яку варто відкрити, запропонована плашкою — без кліку на неї ніколи не переходять
`metadata.language`	мова, якою написана відповідь
`metadata.had_insufficient_context`	база знань не відповіла: пошук не знайшов нічого понад поріг, або помічник сам вирішив, що сторінки не відповідають на питання
`metadata.search_calls`	скільки пошуків зробив хід (0 для привітання)

Ключі, яких не оголошують pydantic-моделі, на цьому ендпоінті відкидаються — referral_kind у дії, relevance у цитаті; сокет їх надсилає. Хід на місячній стелі все одно повертає 200: answer — повідомлення про ліміт, а списки порожні.

Статуси

Статус	Коли	`detail`
`401`	ключа немає або він невідомий	`Missing widget key` / `Invalid widget key`
`403`	ключ неактивний, origin не дозволений або віджет вимкнено	`Widget key is inactive` / `Origin not allowed` / `This assistant is switched off`
`404`	невідомий помічник або розмова не цього сайту	`Unknown agent for this key` / `Conversation not found`
`409`	у віджета немає помічника (порожній `agent_code`)	`This widget has no agent assigned`
`422`	валідація тіла, або модель відмовилася відповідати на це повідомлення	список помилок pydantic / `The assistant declined to answer this message.`
`429`	хвилинний ліміт акаунта, або хвилинний чи добовий ліміт цього відвідувача	`Rate limit exceeded. Please slow down.`
`503`	модель не відповіла	`The assistant is temporarily unavailable. Please try again.`

Продовження розмови

Передайте назад отриманий conversation_id. Сервер тримає пам’ять розмови і відкриті пропозиції — сторінку, про яку спитав, притриману подію, — тож відповідь «так» оцінюється відносно пропозиції. conversation_id, якого сервер уже не знає, — це 404; починайте нову.