API reference
Messages
Send (asynchronous), check the status and list the history.
Send a message (accepted immediately, sent asynchronously)#
POST/messages
- Authentication
- API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
- Required scope
messages:send
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Replaying the same request with the same key never sends the message twice. |
Request body (JSON)
| Field | Type | Description | |
|---|---|---|---|
phoneNumberId | string | required | ID of the number (returned by /connected-businesses/:id/phone-numbers) |
to | string | required | Recipient, international format |
type | string | required | Message type: text, template, image, video, audio, document or location.Values: text, template, image, document, video, audio, location |
text | object | optional | For type: text: { body, previewUrl? }. The body is 1 to 4,096 characters. Requires an open conversation (24-hour window). |
template | object | optional | For type: template: { name, language, components? }. The template must be approved by Meta. |
image | object | optional | For type: image: { link | id, caption? }. link is a public https URL, id is a media already hosted by Meta. |
video | object | optional | For type: video: { link | id, caption? }. |
audio | object | optional | For type: audio: { link | id }. |
document | object | optional | For type: document: { link | id, caption?, filename? }. |
location | object | optional | For type: location: { latitude, longitude, name?, address? }. |
Example
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": "appointment_reminder",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Awa"
},
{
"type": "text",
"text": "November 14 at 10 am"
}
]
}
]
}
}'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": "appointment_reminder",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Awa"
},
{
"type": "text",
"text": "November 14 at 10 am"
}
]
}
]
}
}),
});
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": "appointment_reminder",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Awa",
},
{
"type": "text",
"text": "November 14 at 10 am",
},
],
},
],
},
},
)
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' => 'appointment_reminder',
'language' => 'en',
'components' => [
[
'type' => 'body',
'parameters' => [
[
'type' => 'text',
'text' => 'Awa',
],
[
'type' => 'text',
'text' => 'November 14 at 10 am',
],
],
],
],
],
]),
]);
$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": "appointment_reminder",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Awa"
},
{
"type": "text",
"text": "November 14 at 10 am"
}
]
}
]
}
},
"error": null,
"createdAt": "2026-11-12T08:33:45.855Z",
"sentAt": null,
"deliveredAt": null,
"readAt": null
}Message history (paginated, newest first)#
GET/messages
- Authentication
- API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
- Required scope
messages:read
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
phoneNumberId | query | string | ID of the sending number (the id field of a number, returned by /connected-businesses/{id}/phone-numbers). |
direction | query | string | Filter by direction: inbound (received) or outbound (sent).Values: inbound, outbound |
status | query | string | Filter by status: queued, sent, delivered, read, failed or received.Values: queued, sent, delivered, read, failed, received |
limit | query | number | Number of items per page, from 1 to 100. |
cursor | query | string | nextCursor value from the previous page |
Example
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://example.com/ordonnance.pdf",
"caption": "Your prescription",
"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"
}Get a message's status#
GET/messages/{id}
- Authentication
- API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
- Required scope
messages:read
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | string | Message ID. |
Example
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": "appointment_reminder",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"text": "Awa",
"type": "text"
},
{
"text": "November 14 at 10 am",
"type": "text"
}
]
}
]
}
},
"error": null,
"createdAt": "2026-11-12T08:33:45.855Z",
"sentAt": "2026-11-12T08:33:45.891Z",
"deliveredAt": null,
"readAt": null
}