Довідник Context API

Context API віддає стислий зріз про одну сутність: клієнта, тематику, оператора або скіл-групу. У відповіді — дозволені поля зараз і короткі уривки звернень, які це підтверджують. Розмір пакета обмежений, тож його можна передати в CRM або агенту без повної історії чатів.

Навіщо так зроблено і чим стан відрізняється від репліки в чаті — у поясненні «Про те, як Context API збирає контекст».

API сам не запускає Copilot чи інші AI-сценарії. Його викликає ваша інтеграція або MCP-інструмент. API бере інстанс і користувача з авторизованої сесії. Ідентифікатор інстансу в тілі запиту не дає доступу до чужих даних.

Авторизація — як у решти ConnectiveOne API. Див. Як використовувати API.

Єдиний контракт

Маршрут читання використовує одну форму запиту й відповіді для клієнта, тематики, оператора та скіл-групи. Поле version не передавайте: API відхиляє його як некоректний запит. Для читання потрібне готове сховище контексту; прихованого переходу на старий формат facts немає.

Читання контексту

POST /kw/chatrooms/context/retrieve
Authorization: Bearer <access-token>
Content-Type: application/json

API перевіряє права до складання відповіді і ще раз перед видачею. Якщо доступ зник під час запиту, API повертає помилку і не підставляє застарілі дані.

Клієнт

Останні звернення:

{
  "scope": { "entity": "client", "id": 10004 },
  "targets": ["previous_client_appeals"],
  "topK": 8
}

Останні та релевантні звернення:

{
  "scope": { "entity": "client", "id": 10004 },
  "targets": ["previous_client_appeals", "relevant_appeals"],
  "query": "повернення коштів",
  "topK": 8
}

Тематика

{
  "scope": { "entity": "subject", "id": 3 },
  "targets": ["recent_subject_appeals", "relevant_subject_appeals"],
  "query": "доставка затримується"
}

Поле query обов’язкове, якщо серед targets є relevant_appeals або relevant_subject_appeals.

Стан, дії та властивості

{
  "scope": { "entity": "client", "id": 10004 },
  "sections": ["state", "actions", "properties", "evidence"],
  "targets": ["previous_client_appeals", "previous_client_conversations"],
  "actions": { "limit": 20, "actorTypes": ["client", "operator"] },
  "allowPartial": true
}

Якщо sections не передати, API бере типовий набір для сутності; явні targets або діапазон from/to додають evidence, а параметри actions — розділ дій клієнта. query можна передати лише разом із targets. Якщо в sections є evidence, а targets немає, API бере типовий напрям «останні» для цієї сутності.

Якщо sections задано явно без evidence, API відхиляє параметри відбору звернень (targets, query, from, to, maxSnippetsPerAppeal). Невідому комбінацію sections теж.

Для оператора API бере звернення, у яких він брав участь. Для скіл-групи — звернення за покриттям тематик або участю учасників групи.

Якщо потрібне джерело недоступне: без allowPartial запит завершується помилкою; з allowPartial: true розділ приходить зі status: "unavailable" і причиною.

Окреме читання одного розділу клієнта:

Ці маршрути використовують ту саму логіку і права, що й основний маршрут читання.

Напрями targets

Напрями пам’яті клієнта треба передати явно; типовий набір їх не додає сам.

Параметри читання

actions.actorTypes — масив з client, operator, integration, system. Можна передати одне actions.actorType. Обидва поля разом заборонені.

Якщо пакет не вміщається в бюджет, API прибирає найменш пріоритетні уривки й ставить coverage.partial=true з причиною pack_budget.

Що містить відповідь

Відповідь має sections: поточний стан, дії, властивості й матеріали залежно від запиту. Старе поле facts не повертається.

Приклад успішної відповіді:

{
  "status": "success",
  "data": {
    "scope": { "entity": "client", "id": 10004 },
    "sections": {
      "state": { "status": "ready", "operational": [], "recorded": [] },
      "properties": { "status": "ready", "items": [] }
    },
    "citations": [],
    "coverage": { "partial": false, "reasons": [] },
    "budget": { "maxBytes": 65536, "maxTokens": 8000 }
  }
}

Поля клієнта і тематики

Клієнт: name, email, phone, organization_ids. Додаткові поля — лише ті, що дозволені в картці клієнта, з ключем custom.<field-key>. Некоректне або заборонене поле пропускається; решта відповіді лишається.

Тематика: name, alias, parent_id якщо є, confidential. Видалена тематика фактів не повертає.

Повнота відповіді

Неготовність пошуку для всього інстансу і неповнота однієї відповіді — різні речі. Одне звернення, яке не потрапило в пошук, не вимикає Context API. Відповідь, якої воно стосується, має coverage.partial=true і причину.

Типові причини в coverage.reasons: pack_budget, appeal_quarantined, citation_revoked, recent_partial, relevant_partial. citation_text_refreshed означає, що текст цитати оновлено з джерела; відповідь коректна, partial через це не ставиться.

Запис дій і стану

Запис є лише для клієнта. Він не змінює поля CRM, статуси звернень, права чи маршрутизацію. Щоб закрити звернення або оновити картку, викликайте відповідний бізнес-API.

Обидва запити потребують заголовка Idempotency-Key. Повтор тієї самої команди повертає перший результат із replayed: true. Інше тіло з тим самим ключем відхиляється. Поле externalEventId додатково захищає дію від дубля з боку зовнішньої системи.

PUT перевіряє expectedVersion: якщо стан уже змінив інший запис, команда не проходить. Простори імен на кшталт commerce або onboarding належать різним інтеграціям і не перезаписують одні одних випадково. Зарезервовані: operational, system.

Повідомлення клієнта «я оплатив» лишається уривком у evidence. Підтвердженою дією платежу воно не стає, поки інтеграція не зареєструє подію окремо.

Дії в сценарії

Той самий запис і те саме підвантаження доступні з ноди Action. У наявні сценарії вони самі не додаються.

send_request зовнішній HTTP виконує, у сховище контексту відповідь не кладе. Параметри й приклади — на сторінках дій.

Сесії та імпорт

Маршрути для зовнішньої історії й робочого контексту розмови:

API фіксує клієнта під час відкриття сесії. Наступне тіло повідомлення не може підмінити його.

Імпорт зберігає точку відновлення і продовжується з тим самим Idempotency-Key. Тіла запитів дивіться в Swagger: меню допомоги → API документація.

MCP-інструменти

Ті самі права й той самий маршрут читання. Операцій запису в MCP немає.

Імена параметрів — snake_case: client_id, subject_id, operator_id, skill_group_id, sections, actions, top_k, candidate_limit, max_snippets_per_appeal, max_response_bytes, token_budget, timeout_ms.

Помилки

Відповідь містить персональні дані клієнта. Не пишіть її в звичайні логи застосунку.

Якщо запити стабільно повертають 503, зверніться до адміністратора інстансу.

Пов’язані матеріали

• Про те, як Context API збирає контекст
• Дія register_client_context
• Дія load_external_context
• Як використовувати API
• API довідник
• Хаб інтеграцій