# Envoyer des messages

URL: https://wa.genuka.com/docs/messages
Language: French

> Un seul endpoint pour toute la surface de la Cloud API.

```http
POST /api/v1/messages
```

Un envoi porte toujours trois choses : la connexion utilisée, le destinataire, et **exactement un
champ de contenu**.

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "text": "Bonjour 👋"
}
```

Le numéro est au format international. `connectionId` s'obtient via `GET /api/v1/connections`.
Ajoutez `replyTo` avec le `wamid` d'un message reçu pour répondre en citation.

## Les champs de contenu

> [!WARNING]
> **Un seul champ à la fois**
>
> Envoyer deux champs de contenu dans la même requête n'envoie pas deux messages : seul le premier
> reconnu est retenu. Faites deux appels.

### Texte et médias

| Champ      | Contenu                               | Limites                       |
| ---------- | ------------------------------------- | ----------------------------- |
| `text`     | Une chaîne, ou `{ body, previewUrl }` | 4096 caractères               |
| `image`    | JPEG, PNG                             | 5 Mo, légende 1024 caractères |
| `video`    | MP4, 3GPP (H.264 + AAC)               | 16 Mo                         |
| `audio`    | AAC, AMR, MP3, M4A, OGG               | 16 Mo, **pas de légende**     |
| `document` | PDF, DOC(X), XLS(X), PPT(X), TXT      | 100 Mo                        |
| `sticker`  | WebP statique ou animé                | 100 Ko / 500 Ko               |

### Localisation, contacts, réaction

| Champ             | Contenu                                                     |
| ----------------- | ----------------------------------------------------------- |
| `location`        | `{ latitude, longitude, name, address }`                    |
| `locationRequest` | `{ body }` — affiche un bouton « Envoyer la position »      |
| `contacts`        | Un tableau de fiches contact                                |
| `reaction`        | `{ messageId, emoji }` — une chaîne vide retire la réaction |

### Messages interactifs

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "buttons": {
    "body": "Comment peut-on vous aider ?",
    "footer": "Genuka",
    "buttons": [
      { "id": "order", "title": "Ma commande" },
      { "id": "support", "title": "Un problème" }
    ]
  }
}
```

| Champ     | Description                    | Limites                             |
| --------- | ------------------------------ | ----------------------------------- |
| `buttons` | Boutons de réponse rapide      | **3 maximum**, titre 20 caractères  |
| `list`    | Liste de sections et de lignes | 10 sections, **10 lignes au total** |
| `cta`     | Un bouton portant une URL      | `url` + `displayText`               |

La réponse de l'utilisateur arrive par webhook, avec l'`id` du bouton ou de la ligne choisie.

## Templates

Hors de la fenêtre de 24 heures, seul un template approuvé sera délivré.

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "template": {
    "name": "confirmation_commande",
    "language": "fr",
    "body": ["Awa", "CMD-1042"]
  }
}
```

> [!NOTE]
> Un envoi de template ouvre une conversation facturable par Meta sur la WABA du client — Meta
> facture directement le client. Les messages de service envoyés dans la fenêtre de 24 h sont
> gratuits.

Créez et suivez vos templates via `/api/v1/templates`. Un template en statut `PAUSED` ou
`REJECTED` ne peut pas servir : vérifiez son statut avant de lancer une campagne.

## Échappatoire

Si un type de message n'est pas encore exposé, `raw` transmet un fragment Cloud API verbatim :

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "raw": { "type": "interactive", "interactive": { "type": "flow" } }
}
```

Aucune validation n'est appliquée sur `raw` — les erreurs remontent telles quelles depuis Meta.

## Erreurs fréquentes

| Code Meta | Signification                                         | Que faire                        |
| --------- | ----------------------------------------------------- | -------------------------------- |
| `131047`  | Plus de 24 h depuis le dernier message reçu           | Envoyer un template              |
| `131026`  | Destinataire injoignable ou absent de WhatsApp        | Ne pas réessayer                 |
| `131050`  | L'utilisateur s'est désinscrit du marketing           | Ne plus lui envoyer de marketing |
| `131049`  | Plafond marketing atteint pour cet utilisateur        | Réessayer plus tard              |
| `132001`  | Template inexistant ou non approuvé dans cette langue | Vérifier nom et langue           |
| `130429`  | Débit dépassé                                         | Ralentir, réessayer avec backoff |