Référence API
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 (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
- Portée requise
messages:send
Paramètres
| Nom | Emplacement | Type | Description |
|---|---|---|---|
Idempotency-Key | en-tête | string | Rejouer la même requête avec la même clé ne renvoie jamais le message deux fois. |
Corps de la requête (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.Valeurs : text, template, image, document, video, audio, 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? }. |
Exemple
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"
}
]
}
]
}
}'const res = await fetch(`${process.env.INBOX_API}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.INBOX_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "rdv-2026-11-14-client-42",
},
body: JSON.stringify({
"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"
}
]
}
]
}
}),
});
const data = await res.json();import os
import requests
res = requests.post(
f"{os.environ['INBOX_API']}/messages",
headers={
"Authorization": f"Bearer {os.environ['INBOX_KEY']}",
"Idempotency-Key": "rdv-2026-11-14-client-42",
},
json={
"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",
},
],
},
],
},
},
)
print(res.json())<?php
$ch = curl_init(getenv('INBOX_API') . '/messages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('INBOX_KEY'),
'Content-Type: application/json',
'Idempotency-Key: rdv-2026-11-14-client-42',
],
CURLOPT_POSTFIELDS => json_encode([
'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',
],
],
],
],
],
]),
]);
$data = json_decode(curl_exec($ch), true);{
"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 (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
- Portée requise
messages:read
Paramètres
| Nom | Emplacement | Type | Description |
|---|---|---|---|
phoneNumberId | requête | string | Identifiant du numéro d'envoi (champ id d'un numéro, renvoyé par /connected-businesses/{id}/phone-numbers). |
direction | requête | string | Filtrer par sens : inbound (reçus) ou outbound (envoyés).Valeurs : inbound, outbound |
status | requête | string | Filtrer par statut : queued, sent, delivered, read, failed ou received.Valeurs : queued, sent, delivered, read, failed, received |
limit | requête | number | Nombre d'éléments par page, de 1 à 100. |
cursor | requête | string | Valeur nextCursor de la page précédente |
Exemple
curl "$INBOX_API/messages" \
-H "Authorization: Bearer $INBOX_KEY"const res = await fetch(`${process.env.INBOX_API}/messages`, {
headers: {
Authorization: `Bearer ${process.env.INBOX_KEY}`,
},
});
const data = await res.json();import os
import requests
res = requests.get(
f"{os.environ['INBOX_API']}/messages",
headers={
"Authorization": f"Bearer {os.environ['INBOX_KEY']}",
},
)
print(res.json())<?php
$ch = curl_init(getenv('INBOX_API') . '/messages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('INBOX_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);{
"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 (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
- Portée requise
messages:read
Paramètres
| Nom | Emplacement | Type | Description |
|---|---|---|---|
idrequis | chemin | string | Identifiant du message. |
Exemple
curl "$INBOX_API/messages/ID" \
-H "Authorization: Bearer $INBOX_KEY"const res = await fetch(`${process.env.INBOX_API}/messages/ID`, {
headers: {
Authorization: `Bearer ${process.env.INBOX_KEY}`,
},
});
const data = await res.json();import os
import requests
res = requests.get(
f"{os.environ['INBOX_API']}/messages/ID",
headers={
"Authorization": f"Bearer {os.environ['INBOX_KEY']}",
},
)
print(res.json())<?php
$ch = curl_init(getenv('INBOX_API') . '/messages/ID');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('INBOX_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);{
"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
}