# KI-Steuerung und Übergabe an Mitarbeiter

Steuern Sie, wann die KI antwortet und wann ein Mitarbeiter den Chat übernimmt

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

Jeder Chat hat einen Schalter **KI-Steuerung**, mit dem das Team Ihres Kunden den Agenten selbstständig arbeiten lassen oder jederzeit manuell eingreifen kann.

<AiControlPageDemo />

Der Screenshot zeigt ein Gespräch, direkt nachdem die KI `turnOffAiMode` aufgerufen hat: Der Schalter **KI** im Chat-Header ist aus, ein Banner weist den Mitarbeiter darauf hin, dass er manuell antwortet, und die letzte Nachricht stammt von einem Teammitglied.

## KI-Modus umschalten [#toggle-ai-mode]

1. Öffnen Sie einen beliebigen Chat in **Chats** (Dashboard oder mobile App) und klicken Sie auf den **KI-Schalter** — die Änderung greift sofort.
2. Oder per API: `PATCH /api/chats/{chatId}` mit `{ "isUnderAiControl": false }` (Header `X-Access-Token: happ_your_token_here`).

| Zustand                                | Verhalten                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------- |
| **KI an** (`isUnderAiControl: true`)   | Der Agent antwortet automatisch auf neue Nachrichten                      |
| **KI aus** (`isUnderAiControl: false`) | Der Agent pausiert; Nachrichten warten im Dashboard auf einen Mitarbeiter |

Ist die KI aus, steht der Grund in `aiDisableReason`:

| Grund                  | Beschreibung                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `manual`               | Ein Mitarbeiter hat die KI im Dashboard oder per API deaktiviert                                                            |
| `auto`                 | Die KI hat `turnOffAiMode` zur Übergabe ausgelöst                                                                           |
| `insufficient_balance` | Das Unternehmen hat kein Guthaben mehr; die KI schaltet sich automatisch wieder ein, sobald das Guthaben wieder positiv ist |

## Übergabe an Mitarbeiter [#human-handoff]

Das integrierte Tool `turnOffAiMode` ist immer verfügbar. Kommt die KI zu dem Schluss, dass sie nicht helfen kann, ruft sie das Tool auf: `isUnderAiControl` wird auf `false` gesetzt, der Chat wird im Dashboard als „braucht Aufmerksamkeit“ markiert, und das WebSocket-Ereignis `CHAT_MODE_CHANGED` informiert alle Clients. Richten Sie [Telegram-Push-Benachrichtigungen](/docs/integrations/notifications) ein, damit die Team-Gruppe bei jeder Übergabe eine Nachricht bekommt.

Das Verhalten legen Sie im Prompt des Agenten fest:

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

## Automatische Wiederaufnahme und Kontextfenster [#auto-resume-and-context-window]

* Nach einer **automatischen** Übergabe übernimmt die KI wieder von selbst, sobald im Chat Ruhe eingekehrt ist. Die Verzögerung wird pro Agent festgelegt (`aiAutoReturnDelayMinutes`, standardmäßig 30 Minuten). Nach einer **manuellen** Deaktivierung schaltet sich die KI nie automatisch ein — ein Mitarbeiter muss sie wieder aktivieren.
* Der Kontext ist ein gleitendes Fenster, kein fester Zeitausschnitt: Der Agent sieht den jüngsten Teil des Gesprächs, so viel davon in das Kontextbudget des Modells passt, und alles vor der letzten Zusammenfassungsmarke wird durch diese Zusammenfassung ersetzt. Ältere Nachrichten bleiben in der Datenbank und sind über das integrierte Tool `searchPreviousConversations` weiterhin durchsuchbar.

## Übertragung zwischen Agenten [#transfer-between-assistants]

`PATCH /api/chats/{chatId}` mit `{ "assistantId": "new-assistant-uuid" }`. Der neue Agent macht ab der letzten Nachricht weiter; der gesamte Verlauf bleibt erhalten.

## Bündelung von Nachrichten [#message-debouncing]

Mehrere schnell aufeinanderfolgende Nachrichten werden gebündelt: Die Plattform wartet nach der letzten Nachricht **12 Sekunden** Ruhe ab, bevor der Agent antwortet. Chats, deren älteste unbeantwortete Nachricht älter als **30 Sekunden** ist, arbeitet ein Hintergrundprozess ab, der jede Minute läuft. Kunden schicken eine Bestellung oft in mehreren Teilen, deshalb löst erst die vollständige Folge eine einzige Antwort aus. Solange ein Bild oder eine Sprachnachricht noch erkannt wird, verlängert sich das Fenster, bis die Erkennung vorliegt.

## WebSocket-Ereignisse [#websocket-events]

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

Für Echtzeit-Updates verbinden Sie sich mit `wss://api.happ.tools`.

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

## Weiter [#next]

* [Tools und Webhook-Aktionen](/docs/agents/tools) — wie `turnOffAiMode` mit den anderen Tools zusammenspielt
* [Kanäle](/docs/integrations/messengers) — wo Übergaben in den Messengern stattfinden
* [Agenten](/docs/agents) — festlegen, wer vor der Übergabe antwortet