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

# WhatsApp instances

> Understand WhatsApp instances and query their state through the public API.

## Endpoints

| Method | Endpoint                        | Description                          |
| ------ | ------------------------------- | ------------------------------------ |
| `GET`  | `/api/v1/instances`             | Listr les instances de votre compte  |
| `GET`  | `/api/v1/instances/{id}`        | Details d'une instance               |
| `GET`  | `/api/v1/instances/{id}/state`  | État live depuis le provider         |
| `GET`  | `/api/v1/instances/{id}/health` | Warmup / santé d'envoi de l'instance |

Authentication: `x-api-key: <api_key>`

## Qu'est-ce qu'une instance ?

An instance is a WhatsApp number connected to MsgFlash.

You create and connect instances from the dashboard. The public API then lets you read their details and live state.

***

## États possibles

| Status         | Description                          |
| -------------- | ------------------------------------ |
| `disconnected` | Instance existante mais no connectée |
| `connecting`   | Connexion en cours                   |
| `connected`    | Instance prête à envoyer             |

***

## Listr les instances

```bash theme={null}
curl https://srv.msgflash.com/api/v1/instances \
  -H "x-api-key: msgf_live_your_api_key_here"
```

### Parameters

Cette route n'accepte ni query params ni body.

### Success response

```json theme={null}
{
  "data": [
    {
      "id": "inst_uuid",
      "name": "boutique-principale",
      "waNumber": "+33612345678",
      "status": "connected",
      "webhook": null,
      "meta": null,
      "deletedAt": null,
      "createdAt": "2026-04-01T09:00:00.000Z",
      "updatedAt": "2026-04-01T09:10:00.000Z"
    }
  ]
}
```

<Tip>
  Utilisez `data[].id` comme vraie valeur `instanceId` dans `/api/v1/messages/send`, `/api/v1/messages/schedule`, `/api/v1/campaigns` et les autres endpoints d'envoi.
</Tip>

<Warning>
  `name` and `waNumber` do not replace `instanceId`.

  * `id` = technical identifier to send to MsgFlash
  * `name` = human-readable label for the user
  * `waNumber` = connected number shown on screen
</Warning>

### Common errors

| Code                      | HTTP | When                                   |
| ------------------------- | ---- | -------------------------------------- |
| `UNAUTHORIZED`            | 401  | API key missing or invalid             |
| `API_RATE_LIMIT_EXCEEDED` | 429  | More than 10 req/s on the same API key |

***

## Instance details

```bash theme={null}
curl https://srv.msgflash.com/api/v1/instances/INSTANCE_ID \
  -H "x-api-key: msgf_live_your_api_key_here"
```

### Parameters path

| Parameter | Type | Required | Description      |
| --------- | ---- | -------- | ---------------- |
| `id`      | UUID | yes      | ID de l'instance |

```json theme={null}
{
  "data": {
    "id": "inst_uuid",
    "name": "boutique-principale",
    "waNumber": "+33612345678",
    "status": "connected",
    "createdAt": "2026-04-01T09:00:00.000Z",
    "updatedAt": "2026-04-01T09:10:00.000Z"
  }
}
```

### Common errors

| Code        | HTTP | When                                               |
| ----------- | ---- | -------------------------------------------------- |
| `NOT_FOUND` | 404  | Instance does not exist or is outside your account |

## État live

```bash theme={null}
curl https://srv.msgflash.com/api/v1/instances/INSTANCE_ID/state \
  -H "x-api-key: msgf_live_your_api_key_here"
```

### Parameters path

| Parameter | Type | Required | Description      |
| --------- | ---- | -------- | ---------------- |
| `id`      | UUID | yes      | ID de l'instance |

```json theme={null}
{
  "data": {
    "instanceId": "inst_uuid",
    "status": "connected",
    "providerState": "open"
  }
}
```

### Common errors

| Code        | HTTP | When                                               |
| ----------- | ---- | -------------------------------------------------- |
| `NOT_FOUND` | 404  | Instance does not exist or is outside your account |

## Instance health

```bash theme={null}
curl https://srv.msgflash.com/api/v1/instances/INSTANCE_ID/health \
  -H "x-api-key: msgf_live_your_api_key_here"
```

Cette route retourne :

* `safetyState`
* `safetyScore`
* `warmupPolicy`
* `usageWindowSummary`
* `recommendations`

<Note>
  Warmup V1 returns guidance only. It does not yet directly block sends through this endpoint.
</Note>