Skip to main content
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
​
page
integer
Page (défaut : 1)
​
limit
integer
Nombre max (défaut : 50, max : 200)
​
tag
string
Filtrer par tag exact (ex : vip)
​
search
string
Recherche dans nom, JID, téléphone, email
curl "https://api.waaconnect.com/v1/contacts?page=1&limit=20&tag=vip" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
Réponse 200
{
  "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).
cURL
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).
​
phone
string
Numéro sans + — converti en JID automatiquement
​
jid
string
JID complet (22997000000@s.whatsapp.net)
​
name
string
Nom affiché
​
email
string
Adresse email
​
tags
string[]
Liste de tags libres (ex : ["vip", "client"])
​
variables
object
Variables de personnalisation (ex : {"commande": "CMD-001", "ville": "Cotonou"})
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"]}'

{
  "phone": "22997000000",
  "name": "Aicha",
  "tags": ["vip", "client"],
  "variables": { "commande": "CMD-001", "ville": "Cotonou" }
}

​
Import en masse (bulk)

POST /v1/contacts/bulk Crée ou met à jour jusqu’à 500 contacts en une seule requête.
​
contacts
array
required
Tableau de contacts (même structure que POST /v1/contacts)
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"]}
    ]
  }'
Réponse 200
{
  "created": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}

​
Modifier un contact

PATCH /v1/contacts/:jid 
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"]}'

​
Supprimer un contact

DELETE /v1/contacts/:jid
cURL
curl -X DELETE "https://api.waaconnect.com/v1/contacts/22997000000" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
Réponse 200
{ "ok": true }

​
Tags

Les tags sont des étiquettes libres posées directement sur chaque contact. Un contact peut en avoir plusieurs. 
{ "tags": ["vip", "client", "promo-mai"] }
UsageDescription
FiltrageGET /v1/contacts?tag=vip
Envoi en massePOST /v1/sessions/:id/bulk/tag/:tag
Segmentation rapideOrganiser sans créer de groupe
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.

​
Groupes de contacts

​
Lister les groupes

GET /v1/contacts/groups
cURL
curl https://api.waaconnect.com/v1/contacts/groups \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
Réponse 200
[
  {
    "id": "clguid456",
    "name": "Clients VIP",
    "description": "Clients premium",
    "color": "#20b24b",
    "isSmartGroup": false,
    "contactCount": 42
  }
]

​
Créer un groupe

POST /v1/contacts/groups
​
name
string
required
Nom unique du groupe
​
description
string
Description
​
color
string
Couleur hex (ex : #20b24b)
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"}'

​
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.
​
jids
string[]
required
Liste de JIDs ou numéros de téléphone
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"]}'

{
  "jids": [
    "22997000000@s.whatsapp.net",
    "22996000000@s.whatsapp.net"
  ]
}
Réponse 200
{
  "ok": true,
  "added": 2,
  "errors": []
}
Le contact doit déjà exister dans votre carnet d’adresses. Créez-le d’abord avec POST /v1/contacts.

​
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.
cURL
curl -X DELETE "https://api.waaconnect.com/v1/contacts/groups/clguid456/members/22997000000" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
Réponse 200
{ "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.
​
sessionId
string
required
UUID de la session WhatsApp
​
groupId
string
required
ID du groupe de contacts
​
message
string
required
Texte du message. Supporte {name}, {phone} et toute variable contact.
​
delayMs
integer
Délai en ms entre chaque envoi (recommandé : 2000–3000)
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}'

{
  "message": "Bonjour {name}, votre commande {commande} est prête !",
  "delayMs": 2000
}
Réponse 200
{
  "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.
​
sessionId
string
required
UUID de la session WhatsApp
​
tag
string
required
Tag exact à cibler (sensible à la casse)
​
message
string
required
Texte du message. Supporte {name}, {phone} et toute variable contact.
​
delayMs
integer
Délai en ms entre chaque envoi (recommandé : 2000–3000)
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}'
Réponse 200
{
  "ok": true,
  "total": 28,
  "sent": 27,
  "failed": 1,
  "errors": [
    { "jid": "22996000000@s.whatsapp.net", "reason": "send_failed" }
  ]
}
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.

​
Variables de personnalisation

Les templates supportent des variables entre accolades simples :
VariableRemplacement
{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 !