# Контроль AI та передача людині

Керуйте тим, коли відповідає AI, а коли оператор-людина перебирає чат на себе

> Full REST + WebSocket API reference: https://api.happ.tools/reference

Кожен чат має перемикач **контролю AI**, тож команда вашого клієнта може дати асистенту працювати на автопілоті або втрутитися вручну будь-коли.

<AiControlPageDemo />

На скриншоті показано розмову одразу після того, як AI викликав `turnOffAiMode`: перемикач **AI** у заголовку чату вимкнено, банер нагадує оператору, що він відповідає вручну, а останнє повідомлення надходить від колеги.

## Перемикання режиму AI [#перемикання-режиму-ai]

1. Відкрийте будь-який чат у **Чатах** (панель або мобільний додаток) і натисніть **перемикач AI** — він перемикається миттєво.
2. Або через API: `PATCH /api/chats/{chatId}` з `{ "isUnderAiControl": false }` (заголовок `X-Access-Token: happ_your_token_here`).

| Стан                                        | Поведінка                                                      |
| ------------------------------------------- | -------------------------------------------------------------- |
| **AI увімкнено** (`isUnderAiControl: true`) | Асистент автоматично відповідає на нові повідомлення           |
| **AI вимкнено** (`isUnderAiControl: false`) | Асистент призупинено; повідомлення чекають на людину на панелі |

Коли AI вимкнено, `aiDisableReason` фіксує причину:

| Причина                | Опис                                                                          |
| ---------------------- | ----------------------------------------------------------------------------- |
| `manual`               | Людина вимкнула AI з панелі або через API                                     |
| `auto`                 | AI викликав `turnOffAiMode` для передачі                                      |
| `insufficient_balance` | У компанії закінчився баланс; AI повернеться сам, щойно баланс стане додатним |

## Передача людині [#передача-людині]

Вбудований інструмент `turnOffAiMode` завжди доступний. Коли AI вирішує, що не може допомогти, він викликає інструмент, `isUnderAiControl` встановлюється в `false`, чат з'являється на панелі як такий, що потребує уваги, а WebSocket-подія `CHAT_MODE_CHANGED` сповіщає всіх клієнтів. Налаштуйте [Telegram Push-сповіщення](/docs/integrations/notifications), щоб група команди отримувала пінг на кожну передачу.

Скеруйте його з промпта асистента:

```
If the customer asks to speak to a human, or if you cannot resolve
their issue after 2 attempts, use the turnOffAiMode tool to transfer
the conversation to a human operator. Tell the customer that a team
member will respond shortly.
```

## Автовідновлення та контекстне вікно [#auto-resume-and-context-window]

* Після **автоматичної** передачі AI повертається сам, щойно в чаті стає тихо. Затримка задається на асистенті (`aiAutoReturnDelayMinutes`, за замовчуванням 30 хвилин). **Ручне** вимкнення само не відновлюється — вмикає людина.
* Контекст — рухоме вікно, а не проміжок часу: асистент бачить хвіст розмови, що вміщається в бюджет контексту моделі, а все до останньої позначки підсумку замінює той підсумок. Старіші повідомлення лишаються в базі й доступні через вбудований інструмент `searchPreviousConversations`.

## Передача між асистентами [#передача-між-асистентами]

`PATCH /api/chats/{chatId}` з `{ "assistantId": "new-assistant-uuid" }`. Новий асистент продовжує з останнього повідомлення; вся історія зберігається.

## Дебаунсинг повідомлень [#дебаунсинг-повідомлень]

Швидкі серії збираються в пакет: платформа чекає **12 секунд** тиші після останнього повідомлення й лише тоді відповідає, а чат, у якому найстаріше неопрацьоване повідомлення старше за **30 секунд**, забирає свип, що ходить раз на хвилину. Клієнти регулярно надсилають замовлення частинами, тож відповідь одна — на завершену серію. Поки розпізнається зображення або голосове, вікно продовжується до завершення розпізнавання.

## WebSocket-події [#websocket-події]

```json
{
  "type": "CHAT_MODE_CHANGED",
  "payload": {
    "chatId": "uuid",
    "isUnderAiControl": false,
    "aiDisableReason": "auto"
  }
}
```

Підключайтесь до `wss://api.happ.tools` для оновлень у реальному часі.

**API:** [api.happ.tools/reference](https://api.happ.tools/reference)

## Далі [#далі]

* [Інструменти та webhook-дії](/docs/agents/tools) — як `turnOffAiMode` поєднується з іншими інструментами
* [Канали](/docs/integrations/messengers) — де відбуваються передачі через месенджери
* [Асистенти](/docs/agents) — налаштуйте, хто відповідає до передачі