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

# Managing Instances

> Create, connect, and manage WhatsApp instances through their full lifecycle.

# Managing Instances

An **instance** represents a single WhatsApp number connected to Wappfy. Each instance goes through a lifecycle: create, connect, scan QR, use, and eventually disconnect or delete.

## Instance Types

Wappfy supports two providers:

| Type        | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `waha`      | Self-hosted WhatsApp Web API via WAHA Plus. Full feature support including groups, labels, and contacts. |
| `cloud_api` | Meta's official WhatsApp Business Cloud API. Requires a Meta Business account.                           |

## Instance Status Values

Throughout its lifecycle, an instance transitions through these statuses:

| Status         | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `created`      | Instance record exists but has not been started yet.             |
| `starting`     | Instance is booting up and initializing the WhatsApp session.    |
| `scan_qr`      | Instance is waiting for you to scan the QR code with your phone. |
| `connected`    | WhatsApp session is active and ready to send/receive messages.   |
| `disconnected` | Session was stopped or lost connection. Can be reconnected.      |
| `failed`       | Instance encountered an error during startup or connection.      |

## Lifecycle Overview

```mermaid theme={null}
graph LR
    A[created] --> B[starting]
    B --> C[scan_qr]
    C --> D[connected]
    D --> E[disconnected]
    E --> B
    B --> F[failed]
    F --> B
```

***

## Create an Instance

Create a new WhatsApp instance tied to your account.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My WhatsApp",
      "type": "waha"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.wappfy.io/api/instances", {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My WhatsApp",
      type: "waha",
    }),
  });

  const instance = await response.json();
  console.log(instance.data.id); // use this ID for all subsequent calls
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "name": "My WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}
```

***

## Connect an Instance

Start the WhatsApp session. The instance will transition to `starting` and then to `scan_qr`.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}
```

***

## Get the QR Code

Once the instance reaches `scan_qr` status, retrieve the QR code to scan with your phone.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/qr \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/qr",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  // data.qr contains a base64-encoded QR code image
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

<Note>
  The QR code expires after approximately 60 seconds. If it expires before you scan it, call the endpoint again to get a fresh code.
</Note>

Open the QR code image and scan it with **WhatsApp > Linked Devices > Link a Device** on your phone. Once scanned, the instance status will change to `connected`.

***

## Check Instance Status

Poll the status endpoint to know when the instance is ready.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
```

<Tip>
  Instead of polling, set up a [webhook](/guides/webhooks) for `instance.connected` and `instance.qr` events to get notified in real-time.
</Tip>

***

## List All Instances

Retrieve all instances for your account.

```bash theme={null}
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "My WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Support Line",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}
```

***

## Disconnect an Instance

Stop the WhatsApp session without deleting the instance. You can reconnect later.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: YOUR_API_KEY"
```

***

## Restart an Instance

Restart the WhatsApp session. This is useful if the instance is in a `failed` state or behaving unexpectedly.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Note>
  Restarting preserves the linked WhatsApp session. You will not need to scan the QR code again.
</Note>

***

## Logout an Instance

Log out from WhatsApp entirely. This unlinks the phone from the session. You will need to scan the QR code again to reconnect.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Logout completely removes the WhatsApp link. Unlike disconnect, you **must** scan a new QR code to use this instance again.
</Warning>

***

## Delete an Instance

Permanently delete an instance and all its associated data.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  This action is irreversible. All messages, webhooks, and configuration associated with this instance will be permanently deleted.
</Warning>

***

## Full Lifecycle Example

Here is a complete example that creates an instance, connects it, and polls for the QR code:

```bash theme={null}
# 1. Create the instance
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Created instance: $INSTANCE_ID"

# 2. Connect the instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Wait a moment, then fetch the QR code
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: YOUR_API_KEY")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code saved to qr-code.png — scan it with your phone"

# 4. Poll for connected status
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instance is connected and ready!"
    break
  fi
  sleep 2
done
```

***

## Error Handling

| Status Code | Description                                                           |
| ----------- | --------------------------------------------------------------------- |
| `404`       | Instance not found or does not belong to your account.                |
| `409`       | Instance is already in the requested state (e.g., already connected). |
| `422`       | Invalid request body (e.g., missing `name` or invalid `type`).        |
| `429`       | Rate limit exceeded. See [Rate Limits](/rate-limits).                 |