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

# Conversaciones

> Gestiona conversaciones de WhatsApp programáticamente

# Conversaciones

Las conversaciones representan hilos de chat con tus contactos. Cada conversación está vinculada a un contacto y contiene todo el historial de mensajes.

<CardGroup cols={2}>
  <Card title="Listar Conversaciones" icon="list" href="/api-reference/conversations/list">
    Obtén todas las conversaciones con filtros avanzados
  </Card>

  <Card title="Obtener Conversación" icon="eye" href="/api-reference/conversations/get">
    Detalles de una conversación específica
  </Card>

  <Card title="Buscar por Teléfono" icon="phone" href="/api-reference/conversations/by-phone">
    Encuentra una conversación por número
  </Card>

  <Card title="Historial de Mensajes" icon="messages" href="/api-reference/conversations/messages">
    Obtén todos los mensajes de una conversación
  </Card>

  <Card title="Cerrar Conversación" icon="xmark" href="/api-reference/conversations/close">
    Cierra una conversación activa
  </Card>

  <Card title="Control de IA" icon="robot" href="/api-reference/conversations/ai-control">
    Activa, desactiva o pausa la IA por conversación
  </Card>
</CardGroup>

## Scopes requeridos

| Endpoint               | Scope                 |
| ---------------------- | --------------------- |
| Lectura (GET)          | `conversations:read`  |
| Escritura (POST/PATCH) | `conversations:write` |
| Mensajes               | `messages:read`       |

## Estados de conversación

| Estado     | Descripción                                |
| ---------- | ------------------------------------------ |
| `active`   | Conversación abierta y activa              |
| `closed`   | Cerrada manualmente o por inactividad      |
| `archived` | Archivada (oculta de la bandeja principal) |

## Casos de uso comunes

<AccordionGroup>
  <Accordion title="Sincronizar conversaciones con CRM">
    Usa `GET /conversations/v1` con filtros de fecha para obtener conversaciones nuevas y sincronizarlas con tu CRM.

    ```bash theme={null}
    curl "https://api.whaapy.com/conversations/v1?filters=%7B%22updatedFilter%22%3A%22today%22%7D" \
      -H "Authorization: Bearer wha_xxxxx"
    ```
  </Accordion>

  <Accordion title="Detectar conversaciones sin responder">
    Filtra por mensajes no leídos y estado activo para encontrar conversaciones pendientes.

    ```bash theme={null}
    curl "https://api.whaapy.com/conversations/v1?filters=%7B%22statusFilter%22%3A%22unread%22%7D" \
      -H "Authorization: Bearer wha_xxxxx"
    ```
  </Accordion>

  <Accordion title="Automatizar cierre de conversaciones">
    Usa `POST /conversations/v1/:id/close` después de resolver un ticket en tu sistema.

    ```bash theme={null}
    curl -X POST "https://api.whaapy.com/conversations/v1/uuid/close" \
      -H "Authorization: Bearer wha_xxxxx"
    ```
  </Accordion>

  <Accordion title="Pausar IA al tomar control manual">
    Cuando un agente humano toma el control, pausa la IA temporalmente.

    ```bash 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}'
    ```
  </Accordion>
</AccordionGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Enviar Mensajes" icon="paper-plane" href="/api-reference/messages/send">
    Envía mensajes a conversaciones existentes
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Recibe notificaciones de nuevos mensajes
  </Card>
</CardGroup>