# Контроль AI и передача человеку

Управляйте тем, когда отвечает AI, а когда чат берёт на себя оператор-человек

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

В каждом чате есть переключатель **контроля AI**, чтобы команда вашего клиента могла оставить агента на автопилоте или в любой момент вмешаться вручную.

<AiControlPageDemo />

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

## Переключение режима AI [#toggle-ai-mode]

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 возобновится сам, как только баланс станет положительным |

## Передача человеку [#human-handoff]

Встроенный инструмент `turnOffAiMode` доступен всегда. Когда AI решает, что не может помочь, он вызывает инструмент, `isUnderAiControl` становится `false`, чат появляется в панели как требующий внимания, а WebSocket-событие `CHAT_MODE_CHANGED` оповещает всех клиентов. Настройте [push-уведомления в Telegram](/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 минут). После **ручного** выключения AI сам не включается — включить его снова должен человек.
* Контекст — скользящее окно, а не фиксированный отрезок времени: агент видит последнюю часть разговора, которая помещается в контекст модели, а всё, что было до последней отметки саммари, заменено этим саммари. Старые сообщения остаются в базе, и их можно найти встроенным инструментом `searchPreviousConversations`.

## Передача между агентами [#transfer-between-assistants]

`PATCH /api/chats/{chatId}` с `{ "assistantId": "new-assistant-uuid" }`. Новый агент продолжает с последнего сообщения; вся история сохраняется.

## Группировка сообщений [#message-debouncing]

Сообщения, отправленные подряд, объединяются в одну серию: платформа ждёт **12 секунд** тишины после последнего сообщения, прежде чем агент ответит, а чат, где самое старое неотвеченное сообщение ждёт дольше **30 секунд**, подхватывает проверка, которая запускается раз в минуту. Клиенты часто присылают заказ по частям, поэтому агент отвечает один раз — на всю серию целиком. Пока изображение или голосовое сообщение ещё распознаётся, окно продлевается до завершения распознавания.

## WebSocket-события [#websocket-events]

```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)

## Дальше [#next]

* [Инструменты и действия через вебхуки](/docs/agents/tools) — как `turnOffAiMode` сочетается с другими инструментами
* [Каналы](/docs/integrations/messengers) — где происходят передачи в мессенджерах
* [Агенты](/docs/agents) — настройте, кто отвечает до передачи