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

# Contacts & Groupes

> Gérez votre carnet d'adresses, organisez vos contacts en groupes et envoyez des messages en masse avec personnalisation.

Toutes les routes nécessitent le header `x-api-key`.

***

## Vue d'ensemble

WaaConnect vous permet de gérer un carnet d'adresses attaché à votre compte, indépendamment des sessions WhatsApp.

```
Votre compte
│
├── Contacts ── identifiés par JID (22997000000@s.whatsapp.net)
│   ├── name, email, isBlocked
│   ├── tags: ["vip", "client"]       ← étiquettes libres pour segmenter
│   └── variables: { commande: "…" }  ← variables de personnalisation {commande}
│
└── Groupes de contacts ── listes nommées
    ├── "Clients VIP"  → [contact A, contact B]
    └── "Prospects"    → [contact A, contact C]  ← un contact peut être dans plusieurs groupes
```

***

## Contacts

### Lister les contacts

`GET /v1/contacts`

<ParamField query="page" type="integer">
  Page (défaut : `1`)
</ParamField>

<ParamField query="limit" type="integer">
  Nombre max (défaut : `50`, max : `200`)
</ParamField>

<ParamField query="tag" type="string">
  Filtrer par tag exact (ex : `vip`)
</ParamField>

<ParamField query="search" type="string">
  Recherche dans nom, JID, téléphone, email
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.waaconnect.com/v1/contacts?page=1&limit=20&tag=vip" \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{
  "total": 142,
  "page": 1,
  "limit": 50,
  "items": [
    {
      "id": "cluid123",
      "jid": "22997000000@s.whatsapp.net",
      "phone": "22997000000",
      "name": "Aicha",
      "email": "aicha@example.com",
      "tags": ["vip", "client"],
      "variables": { "commande": "CMD-001", "ville": "Cotonou" },
      "isBlocked": false
    }
  ]
}
```

***

### Récupérer un contact

`GET /v1/contacts/:jid`

Accepte le JID complet (`22997000000@s.whatsapp.net`) ou le numéro seul (`22997000000`).

```bash cURL theme={null}
curl "https://api.waaconnect.com/v1/contacts/22997000000" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

***

### Créer / mettre à jour un contact

`POST /v1/contacts`

Crée ou met à jour un contact (upsert par JID). Fournissez `jid` **ou** `phone` (l'un des deux est obligatoire).

<ParamField body="phone" type="string">
  Numéro sans `+` — converti en JID automatiquement
</ParamField>

<ParamField body="jid" type="string">
  JID complet (`22997000000@s.whatsapp.net`)
</ParamField>

<ParamField body="name" type="string">
  Nom affiché
</ParamField>

<ParamField body="email" type="string">
  Adresse email
</ParamField>

<ParamField body="tags" type="string[]">
  Liste de tags libres (ex : `["vip", "client"]`)
</ParamField>

<ParamField body="variables" type="object">
  Variables de personnalisation (ex : `{"commande": "CMD-001", "ville": "Cotonou"}`)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.waaconnect.com/v1/contacts \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"phone": "22997000000", "name": "Aicha", "tags": ["vip"]}'
  ```

  ```json Corps theme={null}
  {
    "phone": "22997000000",
    "name": "Aicha",
    "tags": ["vip", "client"],
    "variables": { "commande": "CMD-001", "ville": "Cotonou" }
  }
  ```
</CodeGroup>

***

### Import en masse (bulk)

`POST /v1/contacts/bulk`

Crée ou met à jour jusqu'à **500 contacts** en une seule requête.

<ParamField body="contacts" type="array" required>
  Tableau de contacts (même structure que `POST /v1/contacts`)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.waaconnect.com/v1/contacts/bulk \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "contacts": [
        {"phone": "22997000000", "name": "Aicha", "tags": ["vip"]},
        {"phone": "22996000000", "name": "Koffi", "tags": ["prospect"]}
      ]
    }'
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{
  "created": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}
```

***

### Modifier un contact

`PATCH /v1/contacts/:jid`

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.waaconnect.com/v1/contacts/22997000000" \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"name": "Aicha Koné", "tags": ["vip", "fidele"]}'
  ```
</CodeGroup>

***

### Supprimer un contact

`DELETE /v1/contacts/:jid`

```bash cURL theme={null}
curl -X DELETE "https://api.waaconnect.com/v1/contacts/22997000000" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

```json Réponse 200 theme={null}
{ "ok": true }
```

***

## Tags

Les **tags** sont des étiquettes libres posées directement sur chaque contact. Un contact peut en avoir plusieurs.

```json theme={null}
{ "tags": ["vip", "client", "promo-mai"] }
```

| Usage               | Description                           |
| ------------------- | ------------------------------------- |
| Filtrage            | `GET /v1/contacts?tag=vip`            |
| Envoi en masse      | `POST /v1/sessions/:id/bulk/tag/:tag` |
| Segmentation rapide | Organiser sans créer de groupe        |

<Info>
  **Tag vs Groupe** — Le tag est une étiquette sur le contact (modifiable via `PATCH /contacts/:jid`). Le groupe est une liste séparée avec un nom. Un contact peut appartenir à plusieurs groupes simultanément.
</Info>

***

## Groupes de contacts

### Lister les groupes

`GET /v1/contacts/groups`

```bash cURL theme={null}
curl https://api.waaconnect.com/v1/contacts/groups \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

```json Réponse 200 theme={null}
[
  {
    "id": "clguid456",
    "name": "Clients VIP",
    "description": "Clients premium",
    "color": "#20b24b",
    "isSmartGroup": false,
    "contactCount": 42
  }
]
```

***

### Créer un groupe

`POST /v1/contacts/groups`

<ParamField body="name" type="string" required>
  Nom unique du groupe
</ParamField>

<ParamField body="description" type="string">
  Description
</ParamField>

<ParamField body="color" type="string">
  Couleur hex (ex : `#20b24b`)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.waaconnect.com/v1/contacts/groups \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"name": "Clients VIP", "color": "#20b24b"}'
  ```
</CodeGroup>

***

### Ajouter des contacts à un groupe

`POST /v1/contacts/groups/:groupId/members`

Ajoute des contacts par leur JID ou numéro. Un contact peut être dans **plusieurs groupes simultanément** — l'ajout ici ne le retire pas des autres groupes.

<ParamField body="jids" type="string[]" required>
  Liste de JIDs ou numéros de téléphone
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.waaconnect.com/v1/contacts/groups/clguid456/members" \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"jids": ["22997000000@s.whatsapp.net", "22996000000"]}'
  ```

  ```json Corps theme={null}
  {
    "jids": [
      "22997000000@s.whatsapp.net",
      "22996000000@s.whatsapp.net"
    ]
  }
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{
  "ok": true,
  "added": 2,
  "errors": []
}
```

<Warning>
  Le contact doit **déjà exister** dans votre carnet d'adresses. Créez-le d'abord avec `POST /v1/contacts`.
</Warning>

***

### Retirer un contact d'un groupe

`DELETE /v1/contacts/groups/:groupId/members/:jid`

Le contact n'est **pas supprimé** de votre carnet, uniquement retiré de ce groupe.

```bash cURL theme={null}
curl -X DELETE "https://api.waaconnect.com/v1/contacts/groups/clguid456/members/22997000000" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

```json Réponse 200 theme={null}
{ "ok": true }
```

***

## Envoi en masse

### Par groupe

`POST /v1/sessions/:sessionId/bulk/contact-group/:groupId`

Envoie un message à **tous les membres du groupe**. La session doit être connectée.

<ParamField path="sessionId" type="string" required>
  UUID de la session WhatsApp
</ParamField>

<ParamField path="groupId" type="string" required>
  ID du groupe de contacts
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message. Supporte `{name}`, `{phone}` et toute variable contact.
</ParamField>

<ParamField body="delayMs" type="integer">
  Délai en ms entre chaque envoi (recommandé : 2000–3000)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.waaconnect.com/v1/sessions/uuid-session-12/bulk/contact-group/clguid456" \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"message": "Bonjour {name}, offre spéciale disponible !", "delayMs": 2000}'
  ```

  ```json Corps theme={null}
  {
    "message": "Bonjour {name}, votre commande {commande} est prête !",
    "delayMs": 2000
  }
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{
  "ok": true,
  "total": 5,
  "sent": 4,
  "failed": 1,
  "errors": [
    { "jid": "22997000000@s.whatsapp.net", "reason": "contact_not_on_whatsapp" }
  ]
}
```

***

### Par tag

`POST /v1/sessions/:sessionId/bulk/tag/:tag`

Envoie un message à **tous les contacts portant un tag** spécifique.

<ParamField path="sessionId" type="string" required>
  UUID de la session WhatsApp
</ParamField>

<ParamField path="tag" type="string" required>
  Tag exact à cibler (sensible à la casse)
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message. Supporte `{name}`, `{phone}` et toute variable contact.
</ParamField>

<ParamField body="delayMs" type="integer">
  Délai en ms entre chaque envoi (recommandé : 2000–3000)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.waaconnect.com/v1/sessions/uuid-session-12/bulk/tag/vip" \
    -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"message": "Bonjour {name}, offre VIP !", "delayMs": 2000}'
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{
  "ok": true,
  "total": 28,
  "sent": 27,
  "failed": 1,
  "errors": [
    { "jid": "22996000000@s.whatsapp.net", "reason": "send_failed" }
  ]
}
```

<Info>
  **Groupe vs Tag** — Pour l'envoi par groupe, l'ID du groupe est dans l'URL (`.../bulk/contact-group/:groupId`). Pour l'envoi par tag, le tag est dans l'URL (`.../bulk/tag/:tag`). Les deux acceptent `message` et `delayMs` dans le corps.
</Info>

***

## Variables de personnalisation

Les templates supportent des variables entre accolades simples :

| Variable  | Remplacement                             |
| --------- | ---------------------------------------- |
| `{name}`  | Nom du contact (numéro si non renseigné) |
| `{phone}` | Numéro sans `@s.whatsapp.net`            |
| `{clé}`   | Valeur de `variables.clé` du contact     |

**Exemple**

```
Bonjour {name}, votre commande {commande} est prête à {ville} !
```

Avec `name: "Aicha"` et `variables: { commande: "CMD-001", ville: "Cotonou" }` :

```
Bonjour Aicha, votre commande CMD-001 est prête à Cotonou !
```