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

# Gestion des instances

> Creez, connectez et gerez les instances WhatsApp tout au long de leur cycle de vie.

# Gestion des instances

Une **instance** represente un numero WhatsApp unique connecte a Wappfy. Chaque instance suit un cycle de vie : creation, connexion, scan du QR code, utilisation, puis eventuellement deconnexion ou suppression.

## Types d'instances

Wappfy prend en charge deux fournisseurs :

| Type        | Description                                                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `waha`      | API WhatsApp Web auto-hebergee via WAHA Plus. Support complet des fonctionnalites, y compris les groupes, les etiquettes et les contacts. |
| `cloud_api` | API Cloud WhatsApp Business officielle de Meta. Necessite un compte Meta Business.                                                        |

## Valeurs de statut des instances

Tout au long de son cycle de vie, une instance transite par ces statuts :

| Statut         | Description                                                                      |
| -------------- | -------------------------------------------------------------------------------- |
| `created`      | L'enregistrement de l'instance existe mais n'a pas encore ete demarre.           |
| `starting`     | L'instance est en cours de demarrage et d'initialisation de la session WhatsApp. |
| `scan_qr`      | L'instance attend que vous scanniez le QR code avec votre telephone.             |
| `connected`    | La session WhatsApp est active et prete a envoyer/recevoir des messages.         |
| `disconnected` | La session a ete arretee ou a perdu la connexion. Peut etre reconnectee.         |
| `failed`       | L'instance a rencontre une erreur lors du demarrage ou de la connexion.          |

## Vue d'ensemble du cycle de vie

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

***

## Creer une instance

Creez une nouvelle instance WhatsApp liee a votre compte.

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

**Reponse :**

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

***

## Connecter une instance

Demarrez la session WhatsApp. L'instance passera au statut `starting` puis a `scan_qr`.

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

**Reponse :**

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

***

## Obtenir le QR code

Une fois que l'instance atteint le statut `scan_qr`, recuperez le QR code pour le scanner avec votre telephone.

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

**Reponse :**

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

<Note>
  Le QR code expire apres environ 60 secondes. S'il expire avant que vous ne le scanniez, appelez a nouveau l'endpoint pour obtenir un nouveau code.
</Note>

Ouvrez l'image du QR code et scannez-la avec **WhatsApp > Appareils connectes > Connecter un appareil** sur votre telephone. Une fois scanne, le statut de l'instance passera a `connected`.

***

## Verifier le statut de l'instance

Interrogez l'endpoint de statut pour savoir quand l'instance est prete.

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

**Reponse :**

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

<Tip>
  Au lieu d'interroger periodiquement, configurez un [webhook](/fr/guides/webhooks) pour les evenements `instance.connected` et `instance.qr` afin d'etre notifie en temps reel.
</Tip>

***

## Lister toutes les instances

Recuperez toutes les instances de votre compte.

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

**Reponse :**

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

***

## Deconnecter une instance

Arretez la session WhatsApp sans supprimer l'instance. Vous pourrez vous reconnecter plus tard.

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

***

## Redemarrer une instance

Redemarrez la session WhatsApp. Cela est utile si l'instance est en etat `failed` ou se comporte de maniere inattendue.

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

<Note>
  Le redemarrage preserve la session WhatsApp liee. Vous n'aurez pas besoin de scanner a nouveau le QR code.
</Note>

***

## Deconnecter un compte WhatsApp (Logout)

Deconnectez-vous completement de WhatsApp. Cela dissocie le telephone de la session. Vous devrez scanner a nouveau le QR code pour vous reconnecter.

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

<Warning>
  Le logout supprime completement le lien WhatsApp. Contrairement a la deconnexion, vous **devez** scanner un nouveau QR code pour reutiliser cette instance.
</Warning>

***

## Supprimer une instance

Supprimez definitivement une instance et toutes les donnees associees.

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

<Warning>
  Cette action est irreversible. Tous les messages, webhooks et configurations associes a cette instance seront definitivement supprimes.
</Warning>

***

## Exemple complet du cycle de vie

Voici un exemple complet qui cree une instance, la connecte et recupere le QR code :

```bash theme={null}
# 1. Creer l'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. Connecter l'instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Attendre un moment, puis recuperer le 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. Interroger le statut jusqu'a la connexion
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
```

***

## Gestion des erreurs

| Code de statut | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `404`          | Instance non trouvee ou n'appartenant pas a votre compte.                |
| `409`          | L'instance est deja dans l'etat demande (par ex., deja connectee).       |
| `422`          | Corps de requete invalide (par ex., `name` manquant ou `type` invalide). |
| `429`          | Limite de debit depassee. Voir [Limites de debit](/fr/rate-limits).      |