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

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

Ця сторінка пояснює, навіщо так зроблено і які межі в API свідомі. Маршрути, поля й коди помилок — у довіднику Context API.

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

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

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

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

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

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

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

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

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

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

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

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

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

Робочий стан 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 фіксує подію й за потреби стан; load_external_context підтягує знімок із дозволеної зовнішньої системи. send_request зовнішній запит виконує і в контекст нічого не зберігає.

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

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

• Довідник Context API — маршрути, параметри, ліміти, помилки
• Дія register_client_context — запис події та стану зі сценарію
• Дія load_external_context — підвантаження з дозволеної зовнішньої системи
• Як використовувати API — авторизація і базові запити
• Що таке інтеграції — місце Context API серед інших способів з’єднання систем
• Хаб інтеграцій