# Messages

Envoyer (asynchrone), consulter le statut et lister l'historique.

## Envoyer un message (accepté immédiatement, envoyé de façon asynchrone)

`POST /messages`

Authentification : clé API, ou session de la console avec X-Environment-Id · portée : messages:send

Paramètres :

| Nom | Emplacement | Type | Description |
|---|---|---|---|
| `Idempotency-Key` | header | string | Rejouer la même requête avec la même clé ne renvoie jamais le message deux fois. |

Corps (JSON) :

| Champ | Type | | Description |
|---|---|---|---|
| `phoneNumberId` | string | requis | Identifiant du numéro (renvoyé par /connected-businesses/:id/phone-numbers) |
| `to` | string | requis | Destinataire, format international |
| `type` | string | requis | Type de message : text, template, image, video, audio, document ou location. |
| `text` | object | optionnel | Pour `type: text` : `{ body, previewUrl? }`. Le corps fait 1 à 4096 caractères. Exige une conversation ouverte (fenêtre de 24 h). |
| `template` | object | optionnel | Pour `type: template` : `{ name, language, components? }`. Le template doit être approuvé par Meta. |
| `image` | object | optionnel | Pour `type: image` : `{ link \| id, caption? }`. `link` est une URL https publique, `id` un média déjà hébergé par Meta. |
| `video` | object | optionnel | Pour `type: video` : `{ link \| id, caption? }`. |
| `audio` | object | optionnel | Pour `type: audio` : `{ link \| id }`. |
| `document` | object | optionnel | Pour `type: document` : `{ link \| id, caption?, filename? }`. |
| `location` | object | optionnel | Pour `type: location` : `{ latitude, longitude, name?, address? }`. |

```bash
curl -X POST "$INBOX_API/messages" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rdv-2026-11-14-client-42" \
  -d '{
    "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "to": "+237600000000",
    "type": "template",
    "template": {
      "name": "rappel_rdv",
      "language": "fr",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Awa"
            },
            {
              "type": "text",
              "text": "14 novembre à 10 h"
            }
          ]
        }
      ]
    }
  }'
```

Réponse 202 :

```json
{
  "id": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
  "direction": "outbound",
  "status": "queued",
  "type": "template",
  "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
  "to": "237600000000",
  "waMessageId": null,
  "content": {
    "type": "template",
    "template": {
      "name": "rappel_rdv",
      "language": "fr",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Awa"
            },
            {
              "type": "text",
              "text": "14 novembre à 10 h"
            }
          ]
        }
      ]
    }
  },
  "error": null,
  "createdAt": "2026-11-12T08:33:45.855Z",
  "sentAt": null,
  "deliveredAt": null,
  "readAt": null
}
```

## Historique des messages (paginé, plus récents d’abord)

`GET /messages`

Authentification : clé API, ou session de la console avec X-Environment-Id · portée : messages:read

Paramètres :

| Nom | Emplacement | Type | Description |
|---|---|---|---|
| `phoneNumberId` | query | string | Identifiant du numéro d'envoi (champ `id` d'un numéro, renvoyé par /connected-businesses/{id}/phone-numbers). |
| `direction` | query | string | Filtrer par sens : `inbound` (reçus) ou `outbound` (envoyés). |
| `status` | query | string | Filtrer par statut : queued, sent, delivered, read, failed ou received. |
| `limit` | query | number | Nombre d'éléments par page, de 1 à 100. |
| `cursor` | query | string | Valeur `nextCursor` de la page précédente |

```bash
curl "$INBOX_API/messages" \
  -H "Authorization: Bearer $INBOX_KEY"
```

Réponse 200 :

```json
{
  "data": [
    {
      "id": "a9691d7a-ee51-4da9-87b2-24cce79a9313",
      "direction": "outbound",
      "status": "sent",
      "type": "location",
      "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
      "to": "237611111111",
      "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "content": {
        "type": "location",
        "location": {
          "name": "Cabinet Dentaire Zokem",
          "address": "Akwa, Douala",
          "latitude": 4.0511,
          "longitude": 9.7679
        }
      },
      "error": null,
      "createdAt": "2026-11-12T08:33:46.131Z",
      "sentAt": "2026-11-12T08:33:46.251Z",
      "deliveredAt": null,
      "readAt": null
    },
    {
      "id": "9e09a76b-537b-4d5f-8454-4305ba8748a6",
      "direction": "outbound",
      "status": "sent",
      "type": "document",
      "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
      "to": "237611111111",
      "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "content": {
        "type": "document",
        "media": {
          "link": "https://exemple.com/ordonnance.pdf",
          "caption": "Votre ordonnance",
          "filename": "ordonnance.pdf"
        }
      },
      "error": null,
      "createdAt": "2026-11-12T08:33:46.098Z",
      "sentAt": "2026-11-12T08:33:46.221Z",
      "deliveredAt": null,
      "readAt": null
    }
  ],
  "nextCursor": "MjAyNi0xMS0xMlQwODozMzo0Ni4wOThafGMwYmU4NDdlLWQyNDQtNGUyOS04N2M1LTAyNTE3ODk1Yzg5OQ"
}
```

## Statut d'un message

`GET /messages/{id}`

Authentification : clé API, ou session de la console avec X-Environment-Id · portée : messages:read

Paramètres :

| Nom | Emplacement | Type | Description |
|---|---|---|---|
| `id` | path | string |  |

```bash
curl "$INBOX_API/messages/ID" \
  -H "Authorization: Bearer $INBOX_KEY"
```

Réponse 200 :

```json
{
  "id": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
  "direction": "outbound",
  "status": "sent",
  "type": "template",
  "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
  "to": "237600000000",
  "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "content": {
    "type": "template",
    "template": {
      "name": "rappel_rdv",
      "language": "fr",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "text": "Awa",
              "type": "text"
            },
            {
              "text": "14 novembre à 10 h",
              "type": "text"
            }
          ]
        }
      ]
    }
  },
  "error": null,
  "createdAt": "2026-11-12T08:33:45.855Z",
  "sentAt": "2026-11-12T08:33:45.891Z",
  "deliveredAt": null,
  "readAt": null
}
```