# Conversations et contacts

> Index de la documentation : https://wahasend.com/docs/fr/llms.txt · Tout en un fichier : https://wahasend.com/docs/fr.md · URL de base de l'API : https://app.wahasend.com/api/v1

Lisez ce que votre numéro a envoyé et reçu, une conversation par personne, et cherchez des contacts. Inclus dans **Connect** (fonction `inbox`). Une personne est identifiée par les chiffres de son numéro, ou par son identifiant `@lid` quand WhatsApp cache le numéro.

<a id="chats-list"></a>

### Lister les conversations

`GET /api/v1/chats`

Les plus récentes d'abord, avec le dernier message et le nombre de non-lus.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

> Une conversation connue seulement par son identifiant a `phone: "…@lid"` ; quand les deux sont connus, `lid` est ajouté. Un dernier message avec fichier ajoute `lastAttachment`, p. ex. `"PDF · invoice.pdf · 240 KB"`.

**Paramètres de requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `limit` | number | non | Par défaut 50, 200 conversations max (les valeurs jusqu'à 500 sont acceptées et donnent 200). |
| `search` | string | non | Partie d'un numéro ou d'un nom. |
| `containerId` | uuid | non | Lequel de vos numéros WhatsApp utiliser ; il l'emporte toujours. Par défaut : votre numéro par défaut (sinon un numéro connecté), ou un numéro du groupe quand [plusieurs numéros](https://wahasend.com/docs/fr/phone-numbers.md#several-numbers) est activé. Ignoré avec une clé de numéro, qui utilise toujours son numéro. |

**Exemple**

curl:

```bash
curl "https://app.wahasend.com/api/v1/chats?limit=20" \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/chats?limit=20', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/chats?limit=20",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "chats": [
    {
      "phone": "22212345678",
      "name": "Aïcha",
      "lastMessage": "Merci, à demain",
      "lastDirection": "in",
      "lastAt": "2026-09-30T10:41:07.000Z",
      "unread": 1
    }
  ]
}
```

<a id="chats-thread"></a>

### Lire une conversation

`GET /api/v1/chats/:phone`

Les derniers messages avec une personne, les plus anciens d'abord. Les messages envoyés ont leur `status` de remise.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Paramètres de chemin**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `phone` | string | oui | Chiffres du numéro (avec ou sans `+`) ou l'identifiant `@lid`, encodé pour l'URL. |

**Paramètres de requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `limit` | number | non | Par défaut 50, 500 max. |
| `containerId` | uuid | non | Lequel de vos numéros WhatsApp utiliser ; il l'emporte toujours. Par défaut : votre numéro par défaut (sinon un numéro connecté), ou un numéro du groupe quand [plusieurs numéros](https://wahasend.com/docs/fr/phone-numbers.md#several-numbers) est activé. Ignoré avec une clé de numéro, qui utilise toujours son numéro. |

**Exemple**

curl:

```bash
curl https://app.wahasend.com/api/v1/chats/22212345678 \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/chats/22212345678', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/chats/22212345678",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "phone": "22212345678",
  "name": "Aïcha",
  "messages": [
    {
      "id": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
      "direction": "out",
      "text": "Your order #1042 is ready for pickup.",
      "at": "2026-09-30T10:30:12.000Z",
      "status": "read"
    },
    {
      "id": "9a3e1b77-0c52-4f8e-b1d4-2e6c9f0a7b13",
      "direction": "in",
      "text": "Merci, à demain",
      "at": "2026-09-30T10:41:07.000Z",
      "type": "chat"
    }
  ]
}
```

<a id="chats-unread"></a>

### Messages non lus

`GET /api/v1/chats/unread`

Messages reçus que personne n'a marqués lus, les plus anciens d'abord. Ne les marque pas.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Paramètres de requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `limit` | number | non | Par défaut 100, 500 max. |
| `containerId` | uuid | non | Lequel de vos numéros WhatsApp utiliser ; il l'emporte toujours. Par défaut : votre numéro par défaut (sinon un numéro connecté), ou un numéro du groupe quand [plusieurs numéros](https://wahasend.com/docs/fr/phone-numbers.md#several-numbers) est activé. Ignoré avec une clé de numéro, qui utilise toujours son numéro. |

**Exemple**

curl:

```bash
curl https://app.wahasend.com/api/v1/chats/unread \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/chats/unread', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/chats/unread",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "messages": [
    {
      "id": "9a3e1b77-0c52-4f8e-b1d4-2e6c9f0a7b13",
      "phone": "22212345678",
      "name": "Aïcha",
      "text": "Merci, à demain",
      "type": "chat",
      "at": "2026-09-30T10:41:07.000Z"
    }
  ]
}
```

<a id="chats-ack"></a>

### Marquer des messages lus

`POST /api/v1/chats/unread/ack`

Marque les messages reçus donnés comme lus dans WahaSend (le contact ne voit pas de coches bleues). Une clé de numéro ne marque que les messages de son numéro.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `ids` | uuid[] | oui | 1 à 500 identifiants de la liste des non-lus. |

**Exemple**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/chats/unread/ack \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "9a3e1b77-0c52-4f8e-b1d4-2e6c9f0a7b13"
  ]
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/chats/unread/ack', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "ids": [
      "9a3e1b77-0c52-4f8e-b1d4-2e6c9f0a7b13"
    ]
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/chats/unread/ack",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "ids": [
            "9a3e1b77-0c52-4f8e-b1d4-2e6c9f0a7b13",
        ],
    },
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "marked": 1
}
```

<a id="chats-read"></a>

### Marquer une conversation lue

`POST /api/v1/chats/:phone/read`

Marque comme lu tout ce qui a été reçu de cette personne (avec une clé de numéro : sur son numéro seulement).

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Paramètres de chemin**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `phone` | string | oui | Chiffres du numéro ou identifiant `@lid`. |

**Exemple**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/chats/22212345678/read \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/chats/22212345678/read', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/chats/22212345678/read",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "marked": 3
}
```

<a id="contacts-search"></a>

### Chercher des contacts

`GET /api/v1/contacts`

Cherche dans les contacts du téléphone par nom enregistré, nom WhatsApp ou partie du numéro.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Paramètres de requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `search` | string | oui | 1 à 100 caractères. |
| `limit` | number | non | Par défaut 10, 50 max. |

**Exemple**

curl:

```bash
curl "https://app.wahasend.com/api/v1/contacts?search=A%C3%AFcha" \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/contacts?search=A%C3%AFcha', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/contacts?search=A%C3%AFcha",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "contacts": [
    {
      "id": "5e1b7c3a-9d2f-4a86-b0e4-1c7f9a3d5b62",
      "name": "Aïcha",
      "phone": "22212345678",
      "lid": "104937261508834@lid",
      "saved": true,
      "optedOut": false
    }
  ]
}
```

**Erreurs possibles**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/fr/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.

<a id="contacts-count"></a>

### Compter les contacts

`GET /api/v1/contacts/count`

Combien de contacts sont connus, et quand l'historique récent du téléphone a été importé.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Exemple**

curl:

```bash
curl https://app.wahasend.com/api/v1/contacts/count \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/contacts/count', {
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.get(
    "https://app.wahasend.com/api/v1/contacts/count",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "count": 312,
  "historyImportedAt": "2026-09-29T18:03:55.000Z",
  "importing": false
}
```

<a id="contacts-sync"></a>

### Mettre à jour depuis le téléphone

`POST /api/v1/contacts/sync`

Relit le carnet d'adresses maintenant et importe les conversations récentes en arrière-plan. Le numéro doit être connecté.

- Débloqué par: Connect (`inbox`)
- Clé de numéro : oui

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `containerId` | uuid | non | Lequel de vos numéros WhatsApp utiliser ; il l'emporte toujours. Par défaut : votre numéro par défaut (sinon un numéro connecté), ou un numéro du groupe quand [plusieurs numéros](https://wahasend.com/docs/fr/phone-numbers.md#several-numbers) est activé. Ignoré avec une clé de numéro, qui utilise toujours son numéro. |

**Exemple**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/contacts/sync \
  -H "X-API-Key: $WAHASEND_API_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/contacts/sync', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY },
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/contacts/sync",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
)
print(r.json())
```

**Réponse 200**

```json
{
  "success": true,
  "contacts": 312,
  "saved": 240,
  "lidsLinked": 118,
  "messagesLinked": 6,
  "importing": true
}
```

**Erreurs possibles**

- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/fr/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.
- [`WAHA_ERROR`](https://wahasend.com/docs/fr/errors.md#waha_error) (502): WhatsApp could not complete the request. Try again.
- [`WAHA_SESSION_ERROR`](https://wahasend.com/docs/fr/errors.md#waha_session_error) (503): WhatsApp is not connected.