> ## 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.

# Messages

> Envoyez des messages texte, médias, interactifs et campagnes via l'API 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.

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

<ParamField body="to" type="string" required>
  Numéro de téléphone (sans `+`) ou JID complet (`22997000000@s.whatsapp.net`)
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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."}'
  ```

  ```json Corps theme={null}
  {
    "to": "22997000000",
    "message": "Bonjour, votre commande est prête."
  }
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{ "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.

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

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message
</ParamField>

```bash cURL theme={null}
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.

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="mediaType" type="string" required>
  Type de média : `image`, `video`, `audio`, `document`
</ParamField>

<ParamField body="url" type="string" required>
  URL publique du fichier média
</ParamField>

<ParamField body="mimetype" type="string">
  Type MIME du fichier
</ParamField>

<ParamField body="caption" type="string">
  Légende affichée sous le média
</ParamField>

<ParamField body="filename" type="string">
  Nom du fichier (pour `document`)
</ParamField>

<ParamField body="ptt" type="boolean">
  `true` pour envoyer en note vocale (audio uniquement)
</ParamField>

<CodeGroup>
  ```json Image theme={null}
  {
    "to": "22997000000",
    "mediaType": "image",
    "url": "https://example.com/media/promo.jpg",
    "caption": "Promo de la semaine",
    "mimetype": "image/jpeg"
  }
  ```

  ```json Note vocale theme={null}
  {
    "to": "22997000000",
    "mediaType": "audio",
    "url": "https://example.com/media/voice-note.ogg",
    "mimetype": "audio/ogg",
    "ptt": true
  }
  ```
</CodeGroup>

```bash cURL theme={null}
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.

<ParamField body="chatId" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="body" type="string" required>
  Texte principal du message
</ParamField>

<ParamField body="header" type="string">
  Titre affiché en haut du message
</ParamField>

<ParamField body="footer" type="string">
  Texte affiché en bas du message
</ParamField>

<ParamField body="buttons" type="array">
  Boutons d'action (types : `reply`, `url`, `phone`, `copy`)
</ParamField>

<ParamField body="sections" type="array">
  Sections de liste de sélection
</ParamField>

**Types de boutons**

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

<CodeGroup>
  ```json Boutons theme={null}
  {
    "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" }
    ]
  }
  ```

  ```json Liste de sélection theme={null}
  {
    "chatId": "22997000000",
    "body": "Choisissez une option",
    "sections": [
      {
        "title": "Options",
        "rows": [
          {
            "title": "Option 1",
            "rowId": "opt1",
            "description": "Description 1"
          },
          { "title": "Option 2", "rowId": "opt2" }
        ]
      }
    ]
  }
  ```
</CodeGroup>

```json Réponse 200 theme={null}
{ "ok": true, "id": "uuid-message-451" }
```

***

## Document / Contact / Localisation

`POST /v1/sessions/:sessionId/messages/rich`

Envoie un document, un contact ou une localisation.

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="isGroup" type="boolean">
  `true` si le destinataire est un groupe
</ParamField>

<ParamField body="documentUrl" type="string">
  URL du document à envoyer
</ParamField>

<ParamField body="fileName" type="string">
  Nom du fichier
</ParamField>

<ParamField body="contactName" type="string">
  Nom du contact à partager
</ParamField>

<ParamField body="contactPhone" type="string">
  Téléphone du contact à partager
</ParamField>

<ParamField body="latitude" type="number">
  Latitude de la localisation
</ParamField>

<ParamField body="longitude" type="number">
  Longitude de la localisation
</ParamField>

<ParamField body="locationName" type="string">
  Nom du lieu
</ParamField>

<ParamField body="locationAddress" type="string">
  Adresse du lieu
</ParamField>

<CodeGroup>
  ```json Document theme={null}
  {
    "to": "22997000000",
    "documentUrl": "https://example.com/docs/facture.pdf",
    "fileName": "facture.pdf",
    "mimetype": "application/pdf"
  }
  ```

  ```json Contact theme={null}
  {
    "to": "22997000000",
    "contactName": "Aicha Sales",
    "contactPhone": "22996000000"
  }
  ```

  ```json Localisation theme={null}
  {
    "to": "22997000000",
    "latitude": 6.3703,
    "longitude": 2.3912,
    "locationName": "Agence Cotonou",
    "locationAddress": "Boulevard Saint-Michel, Cotonou"
  }
  ```
</CodeGroup>

***

## Campagne

`POST /v1/sessions/:sessionId/messages/campaign`

Envoi en masse personnalisé avec template et délai anti-ban.

<ParamField body="contacts" type="array" required>
  Liste des contacts — chaque entrée doit avoir `jid` (requis) et
  optionnellement `name`
</ParamField>

<ParamField body="template" type="string">
  Template du message. Utilisez `{name}` pour personnaliser par contact.
</ParamField>

<ParamField body="delayMs" type="number">
  Délai en millisecondes entre chaque envoi (défaut : `0`)
</ParamField>

```bash cURL theme={null}
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
  }'
```

```json Réponse 200 theme={null}
{ "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.

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="variations" type="array" required>
  Liste des variantes du message à envoyer aléatoirement
</ParamField>

<ParamField body="isGroup" type="boolean">
  `true` si le destinataire est un groupe
</ParamField>

<ParamField body="delayMs" type="number">
  Délai entre les envois en millisecondes
</ParamField>

```bash cURL theme={null}
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
  }'
```

```json Réponse 200 theme={null}
{
  "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**.

<ParamField body="to" type="string" required>
  Numéro destinataire (ex : `22997000000`)
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message
</ParamField>

<ParamField body="sendAt" type="string">
  Date/heure précise d'envoi au format ISO 8601 (ex : `2026-05-21T18:00:00Z`).
  **Prioritaire sur `delayMs`**. Mode recommandé.
</ParamField>

<ParamField body="delayMs" type="number">
  Délai en millisecondes à partir de maintenant. Utilisé si `sendAt` est absent.
</ParamField>

<ParamField body="isGroup" type="boolean">
  `true` si le destinataire est un groupe
</ParamField>

<Note>
  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.
</Note>

<CodeGroup>
  ```json Avec date précise (recommandé) theme={null}
  {
    "to": "22997000000",
    "message": "Rappel : votre rendez-vous est dans 1h.",
    "sendAt": "2026-05-21T18:00:00Z"
  }
  ```

  ```json Avec délai relatif theme={null}
  {
    "to": "22997000000",
    "message": "Message dans 10 minutes",
    "delayMs": 600000
  }
  ```
</CodeGroup>

```bash cURL theme={null}
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"}'
```

```json Réponse 200 theme={null}
{
  "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](#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.

<Warning>
  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.
</Warning>

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="message" type="string" required>
  Texte du message
</ParamField>

<ParamField body="everyMs" type="number" required>
  Intervalle de répétition en millisecondes (ex : `86400000` pour 24h)
</ParamField>

<ParamField body="isGroup" type="boolean">
  `true` si le destinataire est un groupe
</ParamField>

```bash cURL theme={null}
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}'
```

```json Réponse 200 theme={null}
{
  "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.

<ParamField body="to" type="string" required>
  Numéro ou JID du destinataire
</ParamField>

<ParamField body="text" type="string" required>
  Texte à envoyer après la simulation de saisie
</ParamField>

<ParamField body="delayMs" type="number">
  Durée de la simulation de saisie en millisecondes
</ParamField>

<ParamField body="isGroup" type="boolean">
  `true` si le destinataire est un groupe
</ParamField>

```bash cURL theme={null}
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}'
```

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

***

## Historique

`GET /v1/sessions/:sessionId/messages`

Historique des messages sortants enregistrés en base.

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

<ParamField query="status" type="string">
  Filtre par statut : `PENDING`, `SENT`, `FAILED`
</ParamField>

<ParamField query="to" type="string">
  Filtre par destinataire exact (JID)
</ParamField>

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

```json Réponse 200 theme={null}
{
  "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.

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

<ParamField query="waitMs" type="integer">
  Long-poll : attendre jusqu'à X ms un nouveau message (0–30000)
</ParamField>

<ParamField query="consume" type="boolean">
  `true` = vide le buffer après lecture (défaut : `true`)
</ParamField>

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

```json Réponse 200 theme={null}
{
  "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](/api-reference/contacts) pour créer des groupes et y ajouter des contacts.

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

***

## Envoi en masse — 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, ex : `vip`)
</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 disponible !", "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, 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](/api-reference/contacts#variables-de-personnalisation).
</Info>