Skip to content

REST API v1 · Sandbox

Developer sandbox

A free workspace with a simulated WhatsApp number, for trying the API, webhooks, bots and the inbox before you pay. Nothing it sends reaches WhatsApp or anyone's phone.

API reference · Developer sandbox

Create a sandbox

  1. Open API keys in the dashboard (Integrations → API keys, at /api-keys) and press Create sandbox. Admins and owners can.
  2. You are switched into a new workspace named after yours, with “sandbox” at the end. Switch back from the workspace menu.
  3. One sandbox per person. Pressing the button again opens the one you have.
  4. Create an API key inside the sandbox. Its keys work only there.

Then follow the quickstart with the sandbox’s key.

What you get

  • The Free plan, with API keys and webhooks open on it. Every other limit is the Free plan's, message allowance included.
  • One connected number, shown as +1 202-555-0100. It is simulated: sends are answered by Fliok itself, never by Meta.
  • Templates you create come back approved a few seconds later, with the template.approved webhook.
  • The AI stays off: the Free plan does not include it.

Endpoints

This one is the sandbox’s own. Any other workspace gets 404, as if the endpoint were not there.

Sandbox

1
  • POST/sandbox/inboundDeveloper sandbox only (404 in any other workspace): a simulated customer writes to your sandbox number — { from, text }, or a tapped reply button (buttonId) or list row (listId). It arrives like a real message, so the inbox, bots, auto replies and your webhooks fireScope messages:send · agent role or higher

Sending and statuses

Send with the API as you would anywhere (POST /api/v1/send). Any number gets the receipts below, except the two test numbers, which fail the way real ones do.

StatusAfter the send is accepted
sent1 second
delivered2 seconds
read5 seconds

Each receipt updates the message, its ticks in the inbox and your message.status webhook, exactly as Meta's would. A test number gets failed (and message.failed) at 2 seconds instead of delivered and read.

Test numbers

NumberWhat happens
+1 202-555-0126Fails with #131026, message undeliverable: the person can't be reached.
+1 202-555-0149Fails with #131049: held back by Meta's per-person limit on marketing messages.

These numbers are from the 555-01xx block set aside for fiction, so they belong to no one.

Make a customer write in

Play a customer writing to your sandbox number. The message arrives like a real one, so the inbox, bots, auto replies and your message.received webhook fire.

POST /api/v1/sandbox/inbound takes { from, text } for a text, { from, buttonId, title } for a tapped reply button, or { from, listId, title } for a picked list row. Give exactly one of text, buttonId or listId. Takes an Idempotency-Key, like every other write.

FieldWhat it is
fromThe customer's number with country code. Required.
nameTheir WhatsApp profile name. Optional.
textA text message.
buttonIdThe id of a reply button they tapped; title is its label.
listIdThe id of a list row they picked; title is its label.
cURL
curl -X POST https://fliok.com/api/v1/sandbox/inbound \
  -H "Authorization: Bearer wa_…" \
  -H "Content-Type: application/json" \
  -d '{"from":"+12025550111","name":"Asha","text":"Hi, is this in stock?"}'
Response
HTTP 202

{
  "ok": true,
  "messageId": "wamid.sandbox.in.…",
  "from": "12025550111"
}

What a sandbox refuses

  • Connecting a real WhatsApp number
  • Buying a plan, an add-on or AI credit
  • Connecting Meta ads, a catalog or Instagram
  • Changing the number's display name

Each is refused with a plain message (403, error sandbox). A WhatsApp feature the sandbox doesn't simulate (block lists, calling, QR codes and the like) answers with Meta's own error shape: code 100, “This call is not available in the sandbox.”