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

# Instances Manage करना

> WhatsApp instances को उनके पूर्ण lifecycle के दौरान बनाएं, connect करें, और manage करें।

# Instances Manage करना

एक **instance** Wappfy से जुड़े एक single WhatsApp number को represent करता है। प्रत्येक instance एक lifecycle से गुजरता है: create, connect, QR scan, उपयोग, और अंत में disconnect या delete।

## Instance Types

Wappfy दो providers को support करता है:

| Type        | विवरण                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `waha`      | WAHA Plus के माध्यम से Self-hosted WhatsApp Web API। Groups, labels, और contacts सहित पूर्ण feature support। |
| `cloud_api` | Meta का official WhatsApp Business Cloud API। Meta Business account आवश्यक है।                               |

## Instance Status Values

अपने lifecycle के दौरान, एक instance इन statuses से गुजरता है:

| Status         | विवरण                                                                       |
| -------------- | --------------------------------------------------------------------------- |
| `created`      | Instance record मौजूद है लेकिन अभी तक शुरू नहीं किया गया।                   |
| `starting`     | Instance boot हो रहा है और WhatsApp session initialize कर रहा है।           |
| `scan_qr`      | Instance आपके phone से QR code scan करने की प्रतीक्षा कर रहा है।            |
| `connected`    | WhatsApp session active है और messages भेजने/प्राप्त करने के लिए तैयार है।  |
| `disconnected` | Session रोक दिया गया या connection टूट गया। फिर से connect किया जा सकता है। |
| `failed`       | Startup या connection के दौरान instance में error आया।                      |

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

***

## एक Instance बनाएं

अपने account से जुड़ा एक नया WhatsApp instance बनाएं।

<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"
  }
}
```

***

## एक Instance Connect करें

WhatsApp session शुरू करें। Instance `starting` और फिर `scan_qr` status में transition करेगा।

```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"
  }
}
```

***

## QR Code प्राप्त करें

जब instance `scan_qr` status तक पहुंच जाए, तो अपने phone से scan करने के लिए QR code प्राप्त करें।

<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>
  QR code लगभग 60 seconds बाद expire हो जाता है। यदि scan करने से पहले यह expire हो जाए, तो नया code प्राप्त करने के लिए endpoint को फिर से call करें।
</Note>

QR code image खोलें और अपने phone पर **WhatsApp > Linked Devices > Link a Device** से इसे scan करें। Scan होने के बाद, instance का status `connected` में बदल जाएगा।

***

## Instance Status जांचें

Instance कब तैयार है यह जानने के लिए status endpoint को poll करें।

```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>
  Polling के बजाय, real-time notifications प्राप्त करने के लिए `instance.connected` और `instance.qr` events के लिए [webhook](/hi/guides/webhooks) सेट अप करें।
</Tip>

***

## सभी Instances की सूची

अपने account की सभी instances प्राप्त करें।

```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"
    }
  ]
}
```

***

## एक Instance Disconnect करें

Instance को delete किए बिना WhatsApp session रोकें। आप बाद में फिर से connect कर सकते हैं।

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

***

## एक Instance Restart करें

WhatsApp session restart करें। यह तब उपयोगी है जब instance `failed` state में हो या अप्रत्याशित व्यवहार कर रहा हो।

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

<Note>
  Restart करने से linked WhatsApp session सुरक्षित रहता है। आपको QR code फिर से scan नहीं करना होगा।
</Note>

***

## एक Instance Logout करें

WhatsApp से पूरी तरह logout करें। यह phone को session से unlink करता है। फिर से connect करने के लिए आपको QR code फिर से scan करना होगा।

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

<Warning>
  Logout WhatsApp link को पूरी तरह हटा देता है। Disconnect के विपरीत, इस instance को फिर से उपयोग करने के लिए आपको **अनिवार्य रूप से** नया QR code scan करना होगा।
</Warning>

***

## एक Instance Delete करें

एक instance और उससे जुड़े सभी data को स्थायी रूप से delete करें।

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

<Warning>
  यह action अपरिवर्तनीय है। इस instance से जुड़े सभी messages, webhooks, और configuration स्थायी रूप से delete हो जाएंगे।
</Warning>

***

## पूर्ण Lifecycle उदाहरण

यहां एक पूर्ण उदाहरण है जो एक instance बनाता है, उसे connect करता है, और QR code के लिए poll करता है:

```bash theme={null}
# 1. 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. Instance connect करें
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. कुछ समय प्रतीक्षा करें, फिर QR code fetch करें
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. Connected status के लिए poll करें
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 | विवरण                                                             |
| ----------- | ----------------------------------------------------------------- |
| `404`       | Instance नहीं मिला या आपके account से संबंधित नहीं है।            |
| `409`       | Instance पहले से अनुरोधित state में है (जैसे, पहले से connected)। |
| `422`       | अमान्य request body (जैसे, `name` गायब है या `type` अमान्य है)।   |
| `429`       | Rate limit पार हो गई। [Rate Limits](/hi/rate-limits) देखें।       |