> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Control de IA por Conversación

> Activa, desactiva o pausa la IA en conversaciones específicas

# Control de IA por Conversación

Controla el comportamiento de la IA a nivel de conversación individual. Útil cuando un agente humano toma el control o cuando quieres que la IA no responda a ciertos clientes.

<CardGroup cols={2}>
  <Card title="Activar/Desactivar" icon="toggle-on">
    Control permanente de IA
  </Card>

  <Card title="Pausar Temporalmente" icon="pause">
    Pausa por X minutos
  </Card>
</CardGroup>

***

## Activar o Desactivar IA

Controla permanentemente si la IA puede responder en esta conversación.

```
PATCH https://api.whaapy.com/conversations/v1/{id}/ai
```

### Parámetros

<ParamField path="id" type="string" required>
  UUID de la conversación
</ParamField>

<ParamField body="aiEnabled" type="boolean" required>
  `true` para activar, `false` para desactivar
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.whaapy.com/conversations/v1/uuid/ai" \
    -H "Authorization: Bearer wha_xxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "aiEnabled": false }'
  ```

  ```javascript Node.js theme={null}
  const conversationId = 'uuid';
  await fetch(
    `https://api.whaapy.com/conversations/v1/${conversationId}/ai`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer wha_xxxxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ aiEnabled: false })
    }
  );
  ```

  ```python Python theme={null}
  import requests

  conversation_id = 'uuid'
  response = requests.patch(
      f'https://api.whaapy.com/conversations/v1/{conversation_id}/ai',
      headers={
          'Authorization': 'Bearer wha_xxxxx',
          'Content-Type': 'application/json'
      },
      json={'aiEnabled': False}
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Configuración actualizada",
    "settings": {
      "aiEnabled": false,
      "aiMode": "auto",
      "aiPausedUntil": null
    }
  }
  ```
</ResponseExample>

***

## Pausar IA Temporalmente

Pausa la IA por un tiempo determinado. Útil cuando un agente humano está atendiendo pero quieres que la IA retome automáticamente después.

```
POST https://api.whaapy.com/conversations/v1/{id}/ai/pause
```

### Parámetros

<ParamField path="id" type="string" required>
  UUID de la conversación
</ParamField>

<ParamField body="duration" type="number" default="5">
  Minutos de pausa (1-1440, máximo 24 horas)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.whaapy.com/conversations/v1/uuid/ai/pause" \
    -H "Authorization: Bearer wha_xxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "duration": 30 }'
  ```

  ```javascript Node.js theme={null}
  const conversationId = 'uuid';
  await fetch(
    `https://api.whaapy.com/conversations/v1/${conversationId}/ai/pause`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wha_xxxxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ duration: 30 })
    }
  );
  ```

  ```python Python theme={null}
  import requests

  conversation_id = 'uuid'
  response = requests.post(
      f'https://api.whaapy.com/conversations/v1/{conversation_id}/ai/pause',
      headers={
          'Authorization': 'Bearer wha_xxxxx',
          'Content-Type': 'application/json'
      },
      json={'duration': 30}
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "pausedUntil": "2026-01-29T11:00:00Z",
    "message": "IA pausada por 30 minutos"
  }
  ```
</ResponseExample>

<Tip>
  Usa la pausa temporal cuando un agente humano está atendiendo pero quieres que la IA retome automáticamente después. Si quieres deshabilitar la IA permanentemente, usa el endpoint `PATCH /ai` con `aiEnabled: false`.
</Tip>

***

## Prioridad de control

La IA responde a un mensaje **solo si TODOS estos niveles están activos**:

```mermaid theme={null}
flowchart TD
    A[Mensaje entrante] --> B{IA Global activa?}
    B -->|No| X[No responde]
    B -->|Sí| C{IA pausada globalmente?}
    C -->|Sí| X
    C -->|No| D{IA activa en conversación?}
    D -->|No| X
    D -->|Sí| E{IA pausada en conversación?}
    E -->|Sí| X
    E -->|No| F[IA responde]
```

### Niveles de control

| Nivel                    | Endpoint                              | Prioridad |
| ------------------------ | ------------------------------------- | --------- |
| Global (todo el negocio) | `POST /agent/toggle`                  | Más alta  |
| Pausa global             | `POST /agent/pause`                   | Alta      |
| Por conversación         | `PATCH /conversations/v1/:id/ai`      | Media     |
| Pausa por conversación   | `POST /conversations/v1/:id/ai/pause` | Baja      |

<Warning>
  Si la IA está desactivada globalmente (`POST /agent/toggle`), no responderá aunque esté activada a nivel de conversación.
</Warning>

***

## Casos de uso

<AccordionGroup>
  <Accordion title="Agente humano toma el control">
    Cuando un agente humano comienza a atender, pausa la IA:

    ```javascript theme={null}
    // Webhook: agente asignado a conversación
    async function onAgentAssigned(conversationId) {
      await fetch(
        `https://api.whaapy.com/conversations/v1/${conversationId}/ai/pause`,
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer wha_xxxxx',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ duration: 60 }) // 1 hora
        }
      );
    }
    ```
  </Accordion>

  <Accordion title="Desactivar IA para cliente VIP">
    Algunos clientes prefieren atención humana exclusiva:

    ```javascript theme={null}
    async function disableAIForVIP(conversationId) {
      await fetch(
        `https://api.whaapy.com/conversations/v1/${conversationId}/ai`,
        {
          method: 'PATCH',
          headers: {
            'Authorization': 'Bearer wha_xxxxx',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ aiEnabled: false })
        }
      );
    }
    ```
  </Accordion>

  <Accordion title="Reactivar IA después de resolver">
    Cuando el agente termina, reactiva la IA:

    ```javascript theme={null}
    async function onTicketResolved(conversationId) {
      await fetch(
        `https://api.whaapy.com/conversations/v1/${conversationId}/ai`,
        {
          method: 'PATCH',
          headers: {
            'Authorization': 'Bearer wha_xxxxx',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ aiEnabled: true })
        }
      );
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Control global vs por conversación

| Característica | Global                     | Por conversación                      |
| -------------- | -------------------------- | ------------------------------------- |
| Afecta a       | Todas las conversaciones   | Solo una conversación                 |
| Endpoint       | `POST /agent/toggle`       | `PATCH /conversations/v1/:id/ai`      |
| Caso de uso    | Mantenimiento, emergencias | Clientes específicos, handoff         |
| Pausa temporal | `POST /agent/pause`        | `POST /conversations/v1/:id/ai/pause` |

<Info>
  Para control global de la IA, consulta la documentación de [Agente IA](/api-reference/agent/overview).
</Info>