# Contrôle de l'IA et transfert à un humain

Décidez quand l'IA répond et quand un opérateur humain reprend la conversation

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

Chaque conversation dispose d'un interrupteur **Contrôle de l'IA** pour que l'équipe de votre client laisse l'agent fonctionner en pilote automatique ou intervienne manuellement à tout moment.

<AiControlPageDemo />

La capture montre une conversation juste après que l'IA a invoqué `turnOffAiMode` : l'interrupteur **IA** dans l'en-tête de la conversation est désactivé, un bandeau rappelle à l'opérateur qu'il répond manuellement, et le dernier message vient d'un collègue.

## Activer ou désactiver le mode IA [#toggle-ai-mode]

1. Ouvrez n'importe quelle conversation dans **Conversations** (tableau de bord ou application mobile) et cliquez sur l'**interrupteur IA** — il bascule immédiatement.
2. Ou via l'API : `PATCH /api/chats/{chatId}` avec `{ "isUnderAiControl": false }` (en-tête `X-Access-Token: happ_your_token_here`).

| État                                          | Comportement                                                                       |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| **IA activée** (`isUnderAiControl: true`)     | L'agent répond automatiquement aux nouveaux messages                               |
| **IA désactivée** (`isUnderAiControl: false`) | L'agent se met en pause ; les messages attendent un humain dans le tableau de bord |

Lorsque l'IA est désactivée, `aiDisableReason` en indique la raison :

| Raison                 | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| `manual`               | Un humain a désactivé l'IA depuis le tableau de bord ou l'API                                  |
| `auto`                 | L'IA a déclenché `turnOffAiMode` pour transférer                                               |
| `insufficient_balance` | L'entreprise n'a plus de crédits ; l'IA reprend d'elle-même dès que le solde redevient positif |

## Transfert à un humain [#human-handoff]

L'outil intégré `turnOffAiMode` est toujours disponible. Lorsque l'IA estime ne pas pouvoir aider, elle appelle l'outil, `isUnderAiControl` passe à `false`, la conversation apparaît dans le tableau de bord comme nécessitant une attention, et un événement WebSocket `CHAT_MODE_CHANGED` notifie tous les clients. Configurez les [notifications push Telegram](/docs/integrations/notifications) pour que le groupe de l'équipe soit alerté à chaque transfert.

Guidez-le depuis le prompt de l'agent :

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

## Reprise automatique et fenêtre de contexte [#auto-resume-and-context-window]

* Après un transfert **auto**, l'IA revient d'elle-même une fois la conversation silencieuse. Le délai se règle par agent (`aiAutoReturnDelayMinutes`, 30 minutes par défaut). Une désactivation **manual** ne reprend jamais automatiquement — un humain doit la réactiver.
* Le contexte est une fenêtre glissante, pas une tranche de temps fixe : l'agent voit la fin de la conversation qui tient dans le budget de contexte du modèle, et tout ce qui précède le dernier repère de résumé est remplacé par ce résumé. Les messages plus anciens restent dans la base de données et peuvent être recherchés avec l'outil intégré `searchPreviousConversations`.

## Transfert entre agents [#transfer-between-assistants]

`PATCH /api/chats/{chatId}` avec `{ "assistantId": "new-assistant-uuid" }`. Le nouvel agent reprend à partir du dernier message ; tout l'historique est conservé.

## Regroupement des messages [#message-debouncing]

Les rafales rapides sont regroupées : la plateforme attend **12 secondes** de silence après le dernier message avant que l'agent ne réponde, et une conversation dont le plus ancien message sans réponse a plus de **30 secondes** est traitée par un balayage qui s'exécute chaque minute. Les clients envoient souvent une commande en plusieurs morceaux, de sorte que seule la rafale complète déclenche une réponse. Tant qu'une image ou un message vocal est en cours de reconnaissance, la fenêtre est prolongée jusqu'à la fin de la reconnaissance.

## Événements WebSocket [#websocket-events]

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

Connectez-vous à `wss://api.happ.tools` pour les mises à jour en temps réel.

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

## Pour aller plus loin [#next]

* [Outils et actions webhook](/docs/agents/tools) — comment `turnOffAiMode` s'articule avec les autres outils
* [Canaux](/docs/integrations/messengers) — où se produisent les transferts dans les messageries
* [Agents](/docs/agents) — configurez qui répond avant le transfert