BeaconBox gives your customers a place to read order updates, and nudges them to look. Your job is to push the update whenever your system learns something: order confirmed, dispatched, delayed, payment failed.
The whole API-key surface is twenty operations across five resources. If you only ever call
POST /messages, that is a complete integration.
The three conventions
Everything awkward about integrating BeaconBox comes from getting one of these wrong.
1. The update is delivered before any nudge
Your call returns once the update is in the customer’s inbox. The email, text or WhatsApp message is queued after that, by a worker, and can be refused for reasons your call never sees.
So the response tells you what was accepted, not what was delivered. Delivery arrives later, through webhooks or by reading the message back.
2. A refused nudge is a reported outcome, not an error
The same rule runs through the whole API. A batch always returns 200 and reports per-item failures. Withdrawing an update that was already withdrawn succeeds and tells you it changed nothing.
3. Anything that can repeat an effect requires an idempotency key
Six operations require an Idempotency-Key header, and a request without one is rejected: the
push, the batch, the retract, both resends, and the WhatsApp erasure. Everything else does not,
because repeating it changes nothing a person can see.
That requirement is what makes retrying safe: a connection that dies with the answer in flight means the answer was lost, not that the work was not done. See Idempotency.
Getting started
The quickstart gets you from a key to a delivered update in about five minutes.
If you would rather read first: Pushing updates is the operation you will spend your time in, Reading outcomes covers what comes back, and Webhooks covers what arrives later.
Clients
Two official SDKs. Both cover the same twenty operations, handle idempotency and retries for you, and verify webhook signatures.
| Package | Requires | |
|---|---|---|
| Python | beaconbox |
3.10+, one dependency (httpx). Sync and async. |
| PHP | beaconbox/beaconbox-php |
8.1+, ext-curl and PSR interfaces. No HTTP client pulled in. |
There is no Node, Go or Ruby client. The API is plain JSON over HTTPS and every sample on this
site has a curl form, so integrating from a language without an SDK is ordinary work rather than
a missing piece. See SDKs.