Get started

Concepts

Accounts, apps, environments, connected businesses, numbers, messages, and events: the Bref Point Inbox vocabulary.

Updated November 12, 2026View as Markdown

The model at a glance#

Who owns what

Account (your company)
 └─ App ("My CRM")
     ├─ sandbox environment ──┐
     └─ production environment┤  each contains, strictly separated:
                              │
                              ├─ API keys
                              ├─ Webhook endpoints
                              └─ Connected businesses (your customers)
                                  └─ WhatsApp Business account (WABA)
                                      ├─ Templates
                                      └─ Numbers
                                          └─ Messages and events

Term	Meaning
Account	You: the developer or software vendor using Bref Point Inbox. It is the isolation unit: no data is ever visible from one account to another.
App	A project on your side. It groups your environments and your keys.
Environment	`sandbox` (testing, free, unlimited) or `production`. Two sealed-off universes.
Connected business	Your customer, the owner of a WhatsApp Business account. You create as many as you have customers.
WhatsApp account (WABA)	Your customer's WhatsApp Business account at Meta. It holds the templates.
Number	A WhatsApp number for sending and receiving, attached to a WhatsApp account. It is the one you identify with `phoneNumberId` to send.
Message	A message sent (`outbound`) or received (`inbound`) by a number.
Event	A notification sent to your webhooks: message received, delivered, read, failed…

The lifecycle of an outbound message#

text

queued ──► sent ──► delivered ──► read
   │         │          │
   └─────────┴──────────┴──► failed

Status	Meaning
`queued`	Accepted by the API, waiting to be sent. The `202` response means exactly this.
`sent`	Handed over to Meta.
`delivered`	Meta delivered the message to the recipient's device.
`read`	The recipient read the message (if their read receipt settings allow it).
`failed`	Rejected or not delivered; `error.code` and `error.message` explain why.
`received`	(`inbound` messages only) message received from a customer.

A status never goes backwards: if Meta delivers events to us out of order or in duplicate, a read message doesn't go back to delivered, and a failure doesn't overwrite a message that was already read.

API principles#

Asynchronous: POST /messages responds right away; the actual send and its retries happen in the background. Track progress through webhooks.
Idempotent: the Idempotency-Key header guarantees that a replayed send is never executed twice. See Reliability.
Isolated: a resource belonging to another account or another environment returns 404, as if it didn't exist.
Observable: every response carries an X-Request-Id header, repeated in errors and in the request log.