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

# Overview

> Lifecycle of your WhatsApp connections: create, connect, configure, and remove

The **Instance** module is the starting point of any RyzeAPI integration. Each instance represents **an active connection to a WhatsApp number**, you can have several per account (one for sales, another for support, another for marketing, for example).

Here you'll find everything you need to:

* **Provision** new instances in your account, optionally already configured with webhook, WebSocket, and Chatwoot in the same request
* **Connect** each one to a number via QR code or pairing code
* **Inspect** the current state and profile data
* **Configure** proxy, behavior settings, and S3 storage
* **Disconnect** (logout) keeping the instance, or **delete** completely

<Info>
  **Current status of an instance** is queried via [`GET /api/instance/list?instanceName=<name>`](/en/api/instance/list). The response includes the connection state, profile, and a summary of integrations (webhook, websocket, chatwoot).
</Info>

## Typical lifecycle

<Steps>
  <Step title="Create">
    [`POST /api/instance/new`](/en/api/instance/create) provisions the instance and returns the **TokenInstance**. The instance is born in the `disconnected` state.
  </Step>

  <Step title="Connect">
    [`GET /api/instance/connect/:instance`](/en/api/instance/connect) generates the QR code (or pairing code) for scanning on the phone.
  </Step>

  <Step title="Verify">
    [`GET /api/instance/list?instanceName=<name>`](/en/api/instance/list) confirms the state has become `connected` and exposes the full data (profile, integrations, settings).
  </Step>

  <Step title="Operate">
    The instance is ready to send/receive messages, manage groups, etc. Webhooks and WebSocket notify state changes in real time.
  </Step>

  <Step title="End">
    Use [`logout`](/en/api/instance/logout) to disconnect while keeping the instance, or [`delete`](/en/api/instance/delete) to remove everything permanently.
  </Step>
</Steps>

## Inline configuration on creation

<Tip>
  The **webhook**, **WebSocket**, and **Chatwoot** blocks can be sent **inside the body of `POST /api/instance/new`**, so the instance is born already integrated, with no need for additional calls. See the full reference at [Create instance](/en/api/instance/create).
</Tip>

<CardGroup cols={3}>
  <Card title="Inline webhook" href="/en/api/instance/create">
    Fields `webhookEnabled`, `webhookURL`, `webhookEvents`, `webhookAuthorization`...
  </Card>

  <Card title="Inline WebSocket" href="/en/api/instance/create">
    Fields `websocketEnabled`, `websocketEvents`, `websocketMediaBase64`.
  </Card>

  <Card title="Inline Chatwoot" href="/en/api/instance/create">
    Fields `chatwootEnabled`, `chatwootBaseUrl`, `chatwootAccountId`, `chatwootApiToken`, `chatwootInboxName`...
  </Card>
</CardGroup>

## Instance management

<CardGroup cols={2}>
  <Card title="Create instance" href="/en/api/instance/create">
    `POST /api/instance/new`, provisions a new one, applying proxy, webhook, websocket, chatwoot, settings, and S3 inline.
  </Card>

  <Card title="List instances" href="/en/api/instance/list">
    `GET /api/instance/list`, all of your account (with TokenAccount) or just your own (with TokenInstance). Accepts `?instanceName=` to filter.
  </Card>

  <Card title="Delete" href="/en/api/instance/delete">
    `DELETE /api/instance/delete/:instance`, removes everything permanently.
  </Card>
</CardGroup>

## WhatsApp connection

<CardGroup cols={2}>
  <Card title="Connect (QR or pairing)" href="/en/api/instance/connect">
    `GET /api/instance/connect/:instance`, generates QR code or pairing code to link the number.
  </Card>

  <Card title="Reconnect" href="/en/api/instance/reconnect">
    `POST /api/instance/reconnect/:instance`, restores a dropped session, no new QR needed.
  </Card>

  <Card title="Logout" href="/en/api/instance/logout">
    `DELETE /api/instance/logout/:instance`, disconnects from WhatsApp keeping the instance (will need a new QR to reconnect).
  </Card>
</CardGroup>

## Instance configuration

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

  <Card title="Update settings" href="/en/api/instance/settings-update">
    `POST /api/instance/settings/:instance`, auto-reject calls, ignore groups, keep online, etc.
  </Card>

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

  <Card title="Update proxy" href="/en/api/instance/proxy-update">
    `POST /api/instance/proxy/:instance`, HTTP, HTTPS, or SOCKS5.
  </Card>

  <Card title="Read S3 configuration" href="/en/api/instance/s3-read">
    `GET /api/instance/getS3/:instance`
  </Card>

  <Card title="Update S3 configuration" href="/en/api/instance/s3-update">
    `POST /api/instance/s3/:instance`, store received media in your own bucket.
  </Card>
</CardGroup>

## Possible instance states

| State          | What it means                                                    |
| -------------- | ---------------------------------------------------------------- |
| `disconnected` | Instance created but no active session                           |
| `connecting`   | Waiting for connection via QR Code or Pairing Code with WhatsApp |
| `connected`    | Ready to send and receive                                        |
| `loggedout`    | User unlinked on the phone or logout was performed via the API   |
| `banned`       | Account banned by WhatsApp                                       |

<Info>
  To inspect the current state, use [`GET /api/instance/list?instanceName=<name>`](/en/api/instance/list). The response includes `connection.state`, `connection.numberJid`, `connection.presenceStatus`, `connection.displayStatus`, and the `profile` object (name, picture, business).
</Info>

## Error shape

The API always returns the same error shape on any endpoint of this module:

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

There is no `code` field, use the HTTP status and the `error.message` text to classify.

## Best practices

<Check>To check the instance state, use `GET /api/instance/list?instanceName=<name>` instead of aggressive polling, webhooks/WebSocket are the recommended way to react to changes.</Check>
<Check>Monitor `instance.state` events via webhook/WebSocket to react to `disconnected` / `loggedout` automatically.</Check>

## Related

<CardGroup cols={2}>
  <Card title="Send messages" icon="paper-plane" href="/en/api/messages/overview">
    Once connected, start sending.
  </Card>

  <Card title="Configure webhook" icon="webhook" href="/en/api/events/overview">
    Receive instance events in real time.
  </Card>
</CardGroup>