Messages - WaaConnect

Toutes les routes de messagerie sont préfixées par /sessions/:sessionId/ et nécessitent le header x-api-key.

Envoyer un texte

POST /v1/sessions/:sessionId/send Envoie un message texte à un contact individuel.

sessionId

string

required

UUID de la session

string

required

Numéro de téléphone (sans +) ou JID complet (22997000000@s.whatsapp.net)

message

string

required

Texte du message

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/send \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "message": "Bonjour, votre commande est prête."}'

{
  "to": "22997000000",
  "message": "Bonjour, votre commande est prête."
}

Réponse 200

{ "ok": true, "id": "uuid-message-451" }

Envoyer (sessionId en body)

POST /v1/sessions/api/send Envoie un message avec le sessionId dans le corps — utile pour les intégrations sans paramètre URL dynamique.

sessionId

string

required

UUID de la session

string

required

Numéro ou JID du destinataire

message

string

required

Texte du message

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/api/send \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "uuid-session-12", "to": "22997000000", "message": "Message API direct"}'

Envoyer un média

POST /v1/sessions/:sessionId/send-media Envoie un média : image, vidéo, audio ou document.

string

required

Numéro ou JID du destinataire

mediaType

string

required

Type de média : image, video, audio, document

url

string

required

URL publique du fichier média

mimetype

string

Type MIME du fichier

caption

string

Légende affichée sous le média

filename

string

Nom du fichier (pour document)

ptt

boolean

true pour envoyer en note vocale (audio uniquement)

{
  "to": "22997000000",
  "mediaType": "image",
  "url": "https://example.com/media/promo.jpg",
  "caption": "Promo de la semaine",
  "mimetype": "image/jpeg"
}

{
  "to": "22997000000",
  "mediaType": "audio",
  "url": "https://example.com/media/voice-note.ogg",
  "mimetype": "audio/ogg",
  "ptt": true
}

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/send-media \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "mediaType": "image", "url": "https://example.com/promo.jpg", "caption": "Promo"}'

Message interactif

POST /v1/sessions/:sessionId/send-interactive Envoie un message interactif avec boutons ou liste de sélection.

chatId

string

required

Numéro ou JID du destinataire

body

string

required

Texte principal du message

header

string

Titre affiché en haut du message

footer

string

Texte affiché en bas du message

buttons

array

Boutons d’action (types : reply, url, phone, copy)

sections

array

Sections de liste de sélection

Types de boutons

`type`	Champs supplémentaires
`reply`	`text`
`url`	`text`, `url`
`phone`	`text`, `phoneNumber`
`copy`	`text`, `copyCode`

{
  "chatId": "22997000000",
  "header": "Offre spéciale",
  "body": "Choisissez une option",
  "footer": "Validité 24h",
  "buttons": [
    { "type": "reply", "text": "Je confirme" },
    { "type": "url", "text": "Voir détails", "url": "https://waaconnect.com/offre" }
  ]
}

{
  "chatId": "22997000000",
  "body": "Choisissez une option",
  "sections": [
    {
      "title": "Options",
      "rows": [
        {
          "title": "Option 1",
          "rowId": "opt1",
          "description": "Description 1"
        },
        { "title": "Option 2", "rowId": "opt2" }
      ]
    }
  ]
}

Réponse 200

{ "ok": true, "id": "uuid-message-451" }

Document / Contact / Localisation

POST /v1/sessions/:sessionId/messages/rich Envoie un document, un contact ou une localisation.

string

required

Numéro ou JID du destinataire

isGroup

boolean

true si le destinataire est un groupe

documentUrl

string

URL du document à envoyer

fileName

string

Nom du fichier

contactName

string

Nom du contact à partager

contactPhone

string

Téléphone du contact à partager

latitude

number

Latitude de la localisation

longitude

number

Longitude de la localisation

locationName

string

Nom du lieu

locationAddress

string

Adresse du lieu

{
  "to": "22997000000",
  "documentUrl": "https://example.com/docs/facture.pdf",
  "fileName": "facture.pdf",
  "mimetype": "application/pdf"
}

{
  "to": "22997000000",
  "contactName": "Aicha Sales",
  "contactPhone": "22996000000"
}

{
  "to": "22997000000",
  "latitude": 6.3703,
  "longitude": 2.3912,
  "locationName": "Agence Cotonou",
  "locationAddress": "Boulevard Saint-Michel, Cotonou"
}

Campagne

POST /v1/sessions/:sessionId/messages/campaign Envoi en masse personnalisé avec template et délai anti-ban.

contacts

array

required

Liste des contacts — chaque entrée doit avoir jid (requis) et optionnellement name

template

string

Template du message. Utilisez {name} pour personnaliser par contact.

delayMs

number

Délai en millisecondes entre chaque envoi (défaut : 0)

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/messages/campaign \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"jid": "22997000000@s.whatsapp.net", "name": "Aicha"},
      {"jid": "22996000000@s.whatsapp.net", "name": "Koffi"}
    ],
    "template": "Bonjour {name}, votre livraison part aujourd'\''hui.",
    "delayMs": 3000
  }'

Réponse 200

{ "ok": true, "count": 2 }

Envoi massif

POST /v1/sessions/:sessionId/messages/bulk-send Alias de /v1/sessions/:sessionId/messages/campaign. Même corps et même réponse.

Variations

POST /v1/sessions/:sessionId/messages/variations Envoie une variation aléatoire parmi plusieurs messages vers un même destinataire.

string

required

Numéro ou JID du destinataire

variations

array

required

Liste des variantes du message à envoyer aléatoirement

isGroup

boolean

true si le destinataire est un groupe

delayMs

number

Délai entre les envois en millisecondes

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/messages/variations \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "22997000000",
    "variations": ["Salut Aicha", "Bonjour Aicha", "Hello Aicha"],
    "delayMs": 1200
  }'

Réponse 200

{
  "ok": true,
  "count": 3,
  "sent": ["Salut Aicha", "Bonjour Aicha", "Hello Aicha"]
}

Message programmé

POST /v1/sessions/:sessionId/messages/schedule Programme un message texte en one-shot. Le job est persisté dans Redis via BullMQ — il survit aux redémarrages du serveur.

string

required

Numéro destinataire (ex : 22997000000)

message

string

required

Texte du message

sendAt

string

Date/heure précise d’envoi au format ISO 8601 (ex : 2026-05-21T18:00:00Z). Prioritaire sur delayMs. Mode recommandé.

delayMs

number

Délai en millisecondes à partir de maintenant. Utilisé si sendAt est absent.

isGroup

boolean

true si le destinataire est un groupe

Le quota journalier est consommé au moment de la programmation, pas à l’envoi. Si sendAt est dans le passé, le message est envoyé immédiatement.

{
  "to": "22997000000",
  "message": "Rappel : votre rendez-vous est dans 1h.",
  "sendAt": "2026-05-21T18:00:00Z"
}

{
  "to": "22997000000",
  "message": "Message dans 10 minutes",
  "delayMs": 600000
}

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/messages/schedule \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "message": "Rappel de rendez-vous à 18h", "sendAt": "2026-05-21T18:00:00Z"}'

Réponse 200

{
  "ok": true,
  "scheduledInMs": 3600000,
  "sendAt": "2026-05-21T18:00:00.000Z",
  "messageId": "uuid-du-message-en-base",
  "jobId": "42"
}

Pour suivre le statut d’un message programmé, utilisez l’endpoint Historique avec le filtre ?status=PENDING. Une fois traité, le statut passe à SENT ou FAILED.

Message récurrent

POST /v1/sessions/:sessionId/messages/recurring Programme un message récurrent envoyé à intervalles réguliers.

Les messages récurrents utilisent setInterval (in-memory). Ils ne survivent pas aux redémarrages du serveur et ne peuvent pas être annulés via l’API.

string

required

Numéro ou JID du destinataire

message

string

required

Texte du message

everyMs

number

required

Intervalle de répétition en millisecondes (ex : 86400000 pour 24h)

isGroup

boolean

true si le destinataire est un groupe

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/messages/recurring \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "message": "Rappel quotidien", "everyMs": 86400000}'

Réponse 200

{
  "ok": true,
  "recurringEveryMs": 86400000,
  "timerId": "Timeout(12)"
}

Simulation de saisie

POST /v1/sessions/:sessionId/messages/typing Simule la saisie en cours puis envoie le message.

string

required

Numéro ou JID du destinataire

text

string

required

Texte à envoyer après la simulation de saisie

delayMs

number

Durée de la simulation de saisie en millisecondes

isGroup

boolean

true si le destinataire est un groupe

cURL

curl -X POST https://api.waaconnect.com/v1/sessions/uuid-session-12/messages/typing \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "text": "Je vous écris tout de suite...", "delayMs": 2000}'

Réponse 200

{ "ok": true }

Historique

GET /v1/sessions/:sessionId/messages Historique des messages sortants enregistrés en base.

limit

integer

Nombre max de résultats (défaut : 50, max : 200)

status

string

Filtre par statut : PENDING, SENT, FAILED

string

Filtre par destinataire exact (JID)

cURL

curl "https://api.waaconnect.com/v1/sessions/uuid-session-12/messages?limit=10&status=SENT" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"

Réponse 200

{
  "count": 2,
  "items": [
    {
      "id": "uuid-message-451",
      "sessionId": "uuid-session-12",
      "toNumber": "22997000000@s.whatsapp.net",
      "content": "Bonjour, votre commande est prête.",
      "status": "SENT",
      "sentAt": "2026-03-26T16:30:10.000Z",
      "createdAt": "2026-03-26T16:30:08.000Z"
    },
    {
      "id": "uuid-message-450",
      "sessionId": "uuid-session-12",
      "toNumber": "22996000000@s.whatsapp.net",
      "content": "Rappel de rendez-vous à 18h",
      "status": "FAILED",
      "sentAt": null,
      "createdAt": "2026-03-26T16:29:00.000Z"
    }
  ]
}

Messages reçus

GET /v1/sessions/:sessionId/incoming Lit les messages reçus en temps réel (buffer en mémoire, sans base de données). Supporte le long-polling.

limit

integer

Nombre max de messages (défaut : 50, max : 200)

waitMs

integer

Long-poll : attendre jusqu’à X ms un nouveau message (0–30000)

consume

boolean

true = vide le buffer après lecture (défaut : true)

cURL

curl "https://api.waaconnect.com/v1/sessions/uuid-session-12/incoming?waitMs=5000&consume=true" \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"

Réponse 200

{
  "count": 1,
  "consumed": true,
  "items": [
    {
      "eventId": 17,
      "sessionId": "uuid-session-12",
      "chatId": "22997000000@s.whatsapp.net",
      "from": "22997000000@s.whatsapp.net",
      "fromMe": false,
      "type": "conversation",
      "content": "Bonjour, vous êtes dispo ?",
      "pushName": "Aicha",
      "messageTimestamp": 1774511000,
      "receivedAt": "2026-03-26T18:12:10.000Z"
    }
  ]
}

Envoi en masse — Par groupe de contacts

POST /v1/sessions/:sessionId/bulk/contact-group/:groupId Envoie un message à tous les contacts d’un groupe. Voir Contacts & Groupes pour créer des groupes et y ajouter des contacts.

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 !", "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" }
  ]
}

Envoi en masse — 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, ex : vip)

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 disponible !", "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, le groupId 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. Voir les variables {name}, {phone}, {clé} dans Contacts & Groupes.

​Envoyer un texte

​Envoyer (sessionId en body)

​Envoyer un média

​Message interactif

​Document / Contact / Localisation

​Campagne

​Envoi massif

​Variations

​Message programmé

​Message récurrent

​Simulation de saisie

​Historique

​Messages reçus

​Envoi en masse — Par groupe de contacts

​Envoi en masse — Par tag

Envoyer un texte

Envoyer (sessionId en body)

Envoyer un média

Message interactif

Document / Contact / Localisation

Campagne

Envoi massif

Variations

Message programmé

Message récurrent

Simulation de saisie

Historique

Messages reçus

Envoi en masse — Par groupe de contacts

Envoi en masse — Par tag