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

# Resumen

> Ciclo de vida de tus conexiones de WhatsApp: crear, conectar, configurar y eliminar

El módulo **Instance** es el punto de partida de cualquier integración con RyzeAPI. Cada instancia representa **una conexión activa a un número de WhatsApp**, puedes tener varias por cuenta (una para ventas, otra para soporte, otra para marketing, por ejemplo).

Aquí encontrarás todo lo que necesitas para:

* **Aprovisionar** nuevas instancias en tu cuenta, opcionalmente ya configuradas con webhook, WebSocket y Chatwoot en la misma solicitud
* **Conectar** cada una a un número vía QR code o pairing code
* **Inspeccionar** el estado actual y los datos de perfil
* **Configurar** proxy, ajustes de comportamiento y almacenamiento S3
* **Desconectar** (logout) manteniendo la instancia, o **eliminar** completamente

<Info>
  El **estado actual de una instancia** se consulta vía [`GET /api/instance/list?instanceName=<name>`](/es/api/instance/list). La respuesta incluye el estado de conexión, el perfil y un resumen de las integraciones (webhook, websocket, chatwoot).
</Info>

## Ciclo de vida típico

<Steps>
  <Step title="Crear">
    [`POST /api/instance/new`](/es/api/instance/create) aprovisiona la instancia y devuelve el **TokenInstance**. La instancia nace en el estado `disconnected`.
  </Step>

  <Step title="Conectar">
    [`GET /api/instance/connect/:instance`](/es/api/instance/connect) genera el QR code (o pairing code) para escanear en el teléfono.
  </Step>

  <Step title="Verificar">
    [`GET /api/instance/list?instanceName=<name>`](/es/api/instance/list) confirma que el estado pasó a `connected` y expone los datos completos (perfil, integraciones, settings).
  </Step>

  <Step title="Operar">
    La instancia está lista para enviar/recibir mensajes, gestionar grupos, etc. Webhooks y WebSocket notifican cambios de estado en tiempo real.
  </Step>

  <Step title="Finalizar">
    Usa [`logout`](/es/api/instance/logout) para desconectar manteniendo la instancia, o [`delete`](/es/api/instance/delete) para eliminar todo permanentemente.
  </Step>
</Steps>

## Configuración inline al crear

<Tip>
  Los bloques **webhook**, **WebSocket** y **Chatwoot** pueden enviarse **dentro del cuerpo de `POST /api/instance/new`**, de modo que la instancia nace ya integrada, sin necesidad de llamadas adicionales. Consulta la referencia completa en [Crear instancia](/es/api/instance/create).
</Tip>

<CardGroup cols={3}>
  <Card title="Webhook inline" href="/es/api/instance/create">
    Campos `webhookEnabled`, `webhookURL`, `webhookEvents`, `webhookAuthorization`...
  </Card>

  <Card title="WebSocket inline" href="/es/api/instance/create">
    Campos `websocketEnabled`, `websocketEvents`, `websocketMediaBase64`.
  </Card>

  <Card title="Chatwoot inline" href="/es/api/instance/create">
    Campos `chatwootEnabled`, `chatwootBaseUrl`, `chatwootAccountId`, `chatwootApiToken`, `chatwootInboxName`...
  </Card>
</CardGroup>

## Gestión de instancias

<CardGroup cols={2}>
  <Card title="Crear instancia" href="/es/api/instance/create">
    `POST /api/instance/new`, aprovisiona una nueva, aplicando proxy, webhook, websocket, chatwoot, settings y S3 inline.
  </Card>

  <Card title="Listar instancias" href="/es/api/instance/list">
    `GET /api/instance/list`, todas las de tu cuenta (con TokenAccount) o solo la propia (con TokenInstance). Acepta `?instanceName=` para filtrar.
  </Card>

  <Card title="Eliminar" href="/es/api/instance/delete">
    `DELETE /api/instance/delete/:instance`, elimina todo permanentemente.
  </Card>
</CardGroup>

## Conexión a WhatsApp

<CardGroup cols={2}>
  <Card title="Conectar (QR o pairing)" href="/es/api/instance/connect">
    `GET /api/instance/connect/:instance`, genera QR code o pairing code para vincular el número.
  </Card>

  <Card title="Reconectar" href="/es/api/instance/reconnect">
    `POST /api/instance/reconnect/:instance`, restaura una sesión caída, sin necesidad de un nuevo QR.
  </Card>

  <Card title="Logout" href="/es/api/instance/logout">
    `DELETE /api/instance/logout/:instance`, desconecta de WhatsApp manteniendo la instancia (necesitará un nuevo QR para reconectar).
  </Card>
</CardGroup>

## Configuración de la instancia

<CardGroup cols={2}>
  <Card title="Leer settings" href="/es/api/instance/settings-read">
    `GET /api/instance/getSettings/:instance`
  </Card>

  <Card title="Actualizar settings" href="/es/api/instance/settings-update">
    `POST /api/instance/settings/:instance`, auto-rechazo de llamadas, ignorar grupos, mantener online, etc.
  </Card>

  <Card title="Leer proxy" href="/es/api/instance/proxy-read">
    `GET /api/instance/getProxy/:instance`
  </Card>

  <Card title="Actualizar proxy" href="/es/api/instance/proxy-update">
    `POST /api/instance/proxy/:instance`, HTTP, HTTPS o SOCKS5.
  </Card>

  <Card title="Leer configuración S3" href="/es/api/instance/s3-read">
    `GET /api/instance/getS3/:instance`
  </Card>

  <Card title="Actualizar configuración S3" href="/es/api/instance/s3-update">
    `POST /api/instance/s3/:instance`, almacena media recibida en tu propio bucket.
  </Card>
</CardGroup>

## Estados posibles de una instancia

| Estado         | Qué significa                                                 |
| -------------- | ------------------------------------------------------------- |
| `disconnected` | Instancia creada pero sin sesión activa                       |
| `connecting`   | Esperando conexión vía QR Code o Pairing Code con WhatsApp    |
| `connected`    | Lista para enviar y recibir                                   |
| `loggedout`    | Usuario desvinculó en el teléfono o se realizó logout vía API |
| `banned`       | Cuenta baneada por WhatsApp                                   |

<Info>
  Para inspeccionar el estado actual, usa [`GET /api/instance/list?instanceName=<name>`](/es/api/instance/list). La respuesta incluye `connection.state`, `connection.numberJid`, `connection.presenceStatus`, `connection.displayStatus` y el objeto `profile` (nombre, foto, business).
</Info>

## Forma del error

La API siempre devuelve la misma forma de error en cualquier endpoint de este módulo:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "<actionable description>"
  }
}
```

No hay un campo `code`, usa el status HTTP y el texto de `error.message` para clasificar.

## Mejores prácticas

<Check>Para verificar el estado de la instancia, usa `GET /api/instance/list?instanceName=<name>` en lugar de polling agresivo, los webhooks/WebSocket son la forma recomendada de reaccionar a los cambios.</Check>
<Check>Monitorea los eventos `instance.state` vía webhook/WebSocket para reaccionar a `disconnected` / `loggedout` automáticamente.</Check>

## Relacionado

<CardGroup cols={2}>
  <Card title="Enviar mensajes" icon="paper-plane" href="/es/api/messages/overview">
    Una vez conectada, comienza a enviar.
  </Card>

  <Card title="Configurar webhook" icon="webhook" href="/es/api/events/overview">
    Recibe eventos de la instancia en tiempo real.
  </Card>
</CardGroup>