API reference

Sandbox

Simulate incoming messages and status changes, without WhatsApp.

Simulate a message received from a customer (sandbox keys only). Triggers the `message.received` webhook.#

POST/sandbox/simulate/inbound-message

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: messages:send

Request body (JSON)

Field	Type		Description
`phoneNumberId`	string	required	ID of a number in the sandbox environment.
`from`	string	required	Number of the simulated sender, international format with “+”.
`text`	string	required	Text of the simulated message.

Example

bash

curl -X POST "$INBOX_API/sandbox/simulate/inbound-message" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "from": "+237611111111",
    "text": "Hello, I'\''d like to reschedule my appointment"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/sandbox/simulate/inbound-message`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "from": "+237611111111",
    "text": "Hello, I'd like to reschedule my appointment"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/sandbox/simulate/inbound-message",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
        "from": "+237611111111",
        "text": "Hello, I'd like to reschedule my appointment",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/sandbox/simulate/inbound-message');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phoneNumberId' => '4d8e654e-d744-4bf3-8211-9ceffcccfe87',
        'from' => '+237611111111',
        'text' => 'Hello, I\'d like to reschedule my appointment',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "messageId": "3f3baf5a-f93e-42e8-8263-ce62dc4aadd6",
  "from": "237611111111",
  "status": "received",
  "simulated": true
}

Advance the status of an outbound message (sandbox keys only). Triggers the matching webhook.#

POST/sandbox/simulate/message-status

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: messages:send

Request body (JSON)

Field	Type		Description
`messageId`	string	required	ID of an outbound message in the sandbox environment.
`status`	string	required	New status: sent, delivered, read or failed. A status never goes backwards, as with Meta.Values: sent, delivered, read, failed

Example

bash

curl -X POST "$INBOX_API/sandbox/simulate/message-status" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
    "status": "delivered"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/sandbox/simulate/message-status`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "messageId": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
    "status": "delivered"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/sandbox/simulate/message-status",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "messageId": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
        "status": "delivered",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/sandbox/simulate/message-status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'messageId' => 'd5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00',
        'status' => 'delivered',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "messageId": "d5ad1e3e-6ab9-4f7f-8e4e-b17104a7bd00",
  "status": "delivered",
  "simulated": true
}