---
title: "Про те, як Context API збирає контекст"
description: "Навіщо потрібен стислий контекст клієнта, чим стан відрізняється від уривка чату і чому запис у контекст не змінює CRM."
---

# Про те, як Context API збирає контекст

Оператору, сценарію чи агенту рідко потрібна вся історія чатів. Потрібна відповідь на кілька питань: хто цей клієнт, що з ним зараз, що вже підтверджено зовні і про що говорили раніше. Context API збирає саме цей стислий зріз — не повну історію діалогів і не всю картку CRM.

Ця сторінка пояснює, навіщо так зроблено і які межі в API свідомі. Маршрути, поля й коди помилок — у [довіднику Context API](/uk/integrations/reference/context-api.md).

## Контекст і проблема

У ConnectiveOne дані про клієнта розкидані: картка, відкриті звернення, листування, події з магазину чи сайту. Якщо кожна інтеграція сама збирає цю картину, виходить різний обсяг, різні права й різне уявлення про «що відбувається зараз».

Типові ситуації:

- Агент має відповісти про повернення і бачити лише дозволені уривки, а не весь архів.
- Магазин уже знає, що замовлення очікує оплату, але цього факту немає в картці клієнта.
- Клієнт у чаті написав «я оплатив» — це репліка, а не підтверджений платіж.

Повний текст листування не підходить як стандартний вхід: він великий, містить зайве і легко обходить ті самі правила доступу, що діють у Панелі оператора (OperatorLine). Context API навмисно віддає малий пакет із посиланнями на джерела.

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

## Основні концепції

Запит завжди про одну сутність: клієнта, тематику, оператора або скіл-групу. Відповідь складається з розділів, кожен з яких відповідає на своє питання.

```mermaid
flowchart LR
    Q[Запит про одну сутність] --> P[Стислий пакет]
    P --> S[Стан зараз]
    P --> A[Зареєстровані дії]
    P --> R[Властивості]
    P --> E[Уривки звернень]
```

### Чотири питання

| Розділ | Питання | Приклад |
|---|---|---|
| Стан | Що відбувається зараз? | Є відкрите звернення; магазин каже «очікує оплату до 12:00» |
| Дії | Які події вже зареєстровані? | Клієнт оформив замовлення, надіслав заявку |
| Властивості | Що відомо про сутність? | Ім’я, контакти, організація, дозволені додаткові поля |
| Докази | На що можна послатися? | Останні або релевантні уривки звернень |

Перша версія відповідає на властивості й докази для клієнта та тематики. Друга додає стан і журнал дій, а також читання оператора й скіл-групи.

### Стан робочий і стан записаний

У клієнта може бути одночасно відкритий чат, очікування доставки й незаповнена форма. Одного загального статусу замало.

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

Записаний стан має строк актуальності. Після нього API більше не показує старе значення як чинне. Порожній простір імен — «невідомо», а не вигаданий статус за замовчуванням.

### Дія — не висновок моделі

Зареєстрована дія має прийти від відповідної інтеграції або сценарію. Платіж, перегляд сторінки чи відправлення форми не можна «вивести» лише з відповіді AI.

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

Відсутність дій у відповіді означає: у доступному журналі немає зареєстрованих подій. Це не доводить, що клієнт нічого не робив.

### Докази з посиланням на джерело

Докази — відібрані звернення й короткі уривки, на які можна послатися. Кожен факт або уривок має цитату: звідки він узятий. Якщо права змінилися або повідомлення вже не можна цитувати, API не підставляє застарілий текст.

Пакет обмежений за розміром і часом збору. Якщо все не вміщається, API позначає відповідь неповною. Краще чесна частковість, ніж обрізане значення, видане за повний факт.

### Хто в запиті і хто має права

Область запиту каже, **про кого** збираємо контекст. Права лишаються за тим, хто запитує.

Запит контексту оператора не дає прав цього оператора. Контекст скіл-групи не відкриває всім членам чужі діалоги. Читання не дає права запису.

Для оператора докази — звернення, де він брав участь, навіть якщо вже вийшов із чату. Це збережений зв’язок участі, а не доказ, що він написав усі повідомлення. Для скіл-групи API типово бере звернення за поточними тематиками групи, а не «історичне призначення групі в момент події».

## Варіанти підходів

### Повний чат проти стислого пакета

Повна історія чату дає максимум тексту. Її важко обмежити для агента, важко перевірити на права, і вона змішує робочі факти з розмовою.

Стислий пакет віддає лише дозволене й обмежене. Мінус: довгий діалог може потрапити в відповідь лише частково. Для ConnectiveOne важливіше не згодувати моделі архів, ніж показати «все, що коли-небудь було».

### Змінити CRM проти записати контекст

Можна писати статус замовлення прямо в картку клієнта або в тікет. Тоді контекст і облікова система зливаються, а випадковий запис ламає маршрутизацію чи поля CRM.

Context API зберігає записаний стан окремо. Він не закриває звернення, не міняє поля картки і не змінює доступність оператора. Команду «закрити звернення» виконує відповідний бізнес-API.

### Один журнал на все проти просторів імен

Спільне поле «статус клієнта» зручне, поки інтеграція одна. Друга інтеграція неминуче затирає першу.

Простір імен відділяє джерела. Додаткове поле картки «етап» і стан покупки «етап» — різні дані. API не обирає «головне» мовчки.

## Прийняті рішення

**Один пакет на одну сутність.** Немає запиту «дай усіх клієнтів із контекстом». Спочатку вибираєте клієнта, тематику, оператора або скіл-групу.

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

**Читання не пише.** Збір пакета не створює історії чатів і не змінює картку.

**Немає прихованого підключення до AI.** Готовність читання не означає, що Copilot уже ходить у цей API. Запис теж не вмикається сам у наявних сценаріях.

**Без прав — без даних.** Якщо джерело недоступне, API не підміняє його застарілою копією. Порожній дозволений набір — нормальна відповідь; недоступне джерело — окрема позначка неповноти.

**Повтор команди не множить подію.** Інтеграція може втратити відповідь і надіслати те саме ще раз. Одна логічна подія лишається однією. API відхиляє інше тіло під тим самим ключем.

## Наслідки для роботи

Не використовуйте Context API, щоб змінити тікет, картку чи чергу. Для цього лишаються звичайні API звернень і клієнтів.

Не кладіть повний текст розмови в атрибути дії. Для зовнішньої історії є окремі сесії й імпорт; довідник описує їхні межі.

Не читайте порожній журнал дій як «клієнт бездіяльний». Дивіться покриття відповіді: журнал може бути ще не заповнений, або подія поза строком зберігання.

Не очікуйте, що MCP уміє записувати стан. Інструменти читають той самий пакет і не обходять права сесії.

У сценарії запис і зовнішнє підвантаження не з’являються самі. Для цього є дві вбудовані дії: [register_client_context](/uk/actionjail/reference/actions/register_client_context.md) фіксує подію й за потреби стан; [load_external_context](/uk/actionjail/reference/actions/load_external_context.md) підтягує знімок із дозволеної зовнішньої системи. `send_request` зовнішній запит виконує і в контекст нічого не зберігає.

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

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

- [Довідник Context API](/uk/integrations/reference/context-api.md) — маршрути, параметри, ліміти, помилки
- [Дія register_client_context](/uk/actionjail/reference/actions/register_client_context.md) — запис події та стану зі сценарію
- [Дія load_external_context](/uk/actionjail/reference/actions/load_external_context.md) — підвантаження з дозволеної зовнішньої системи
- [Як використовувати API](/uk/integrations/how-to/use-api.md) — авторизація і базові запити
- [Що таке інтеграції](/uk/integrations/explanation/what-are-integrations.md) — місце Context API серед інших способів з’єднання систем
- [Хаб інтеграцій](/uk/integrations/integrator-hub.md)