# Control de IA y derivación a una persona

Controla cuándo responde la IA y cuándo un operador humano toma el chat

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

Cada chat tiene un interruptor de **control de IA** para que el equipo de tu cliente deje que el asistente funcione en piloto automático o intervenga manualmente cuando lo necesite.

<AiControlPageDemo />

La captura muestra una conversación justo después de que la IA invocara `turnOffAiMode`: el interruptor **IA** de la cabecera del chat está desactivado, un aviso recuerda al operador que está respondiendo manualmente y el último mensaje es de un compañero.

## Activar o desactivar el modo IA [#toggle-ai-mode]

1. Abre cualquier chat en **Chats** (panel o aplicación móvil) y haz clic en el **interruptor de IA**: cambia de inmediato.
2. O por API: `PATCH /api/chats/{chatId}` con `{ "isUnderAiControl": false }` (encabezado `X-Access-Token: happ_your_token_here`).

| Estado                                         | Comportamiento                                                        |
| ---------------------------------------------- | --------------------------------------------------------------------- |
| **IA activada** (`isUnderAiControl: true`)     | El asistente responde automáticamente a los mensajes nuevos           |
| **IA desactivada** (`isUnderAiControl: false`) | El asistente se pausa; los mensajes esperan en el panel a una persona |

Con la IA desactivada, `aiDisableReason` registra el motivo:

| Motivo                 | Descripción                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `manual`               | Una persona desactivó la IA desde el panel o la API                                           |
| `auto`                 | La IA lanzó `turnOffAiMode` para derivar                                                      |
| `insufficient_balance` | La empresa se quedó sin créditos; la IA se reanuda sola cuando el saldo vuelve a ser positivo |

## Derivación a una persona [#human-handoff]

La herramienta integrada `turnOffAiMode` está siempre disponible. Cuando la IA decide que no puede ayudar, llama a la herramienta, `isUnderAiControl` se pone en `false`, el chat aparece en el panel como pendiente de atención y un evento WebSocket `CHAT_MODE_CHANGED` avisa a todos los clientes. Configura las [notificaciones push de Telegram](/docs/integrations/notifications) para que el grupo del equipo reciba un aviso en cada derivación.

Guíala desde el prompt del asistente:

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

## Reanudación automática y ventana de contexto [#auto-resume-and-context-window]

* Tras una derivación **auto**, la IA vuelve por sí sola cuando el chat se queda en silencio. El retraso se configura por asistente (`aiAutoReturnDelayMinutes`, 30 minutos por defecto). Una desactivación **manual** nunca se reanuda automáticamente: una persona tiene que volver a activarla.
* El contexto es una ventana móvil, no un intervalo de tiempo fijo: el asistente ve el final de la conversación que cabe en el presupuesto de contexto del modelo, y todo lo anterior a la marca del último resumen se sustituye por ese resumen. Los mensajes antiguos se quedan en la base de datos y siguen siendo localizables con la herramienta integrada `searchPreviousConversations`.

## Transferir entre asistentes [#transfer-between-assistants]

`PATCH /api/chats/{chatId}` con `{ "assistantId": "new-assistant-uuid" }`. El nuevo asistente continúa desde el último mensaje; se conserva todo el historial.

## Agrupación de mensajes [#message-debouncing]

Las ráfagas rápidas se agrupan: la plataforma espera **12 segundos** de silencio tras el último mensaje antes de que responda el asistente, y un chat cuyo mensaje sin responder más antiguo tiene más de **30 segundos** lo procesa un barrido que se ejecuta cada minuto. Los clientes suelen enviar un pedido por partes, así que solo la ráfaga completa genera una respuesta. Mientras se reconoce una imagen o un mensaje de voz, la ventana se amplía hasta que termina el reconocimiento.

## Eventos WebSocket [#websocket-events]

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

Conéctate a `wss://api.happ.tools` para recibir actualizaciones en tiempo real.

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

## Siguiente [#next]

* [Herramientas y acciones de webhook](/docs/agents/tools): cómo encaja `turnOffAiMode` con otras herramientas
* [Canales](/docs/integrations/messengers): dónde se producen las derivaciones en las aplicaciones de mensajería
* [Agentes](/docs/agents): configura quién responde antes de la derivación