msgbubblesDocs

Authentication

Every API request carries your secret key in the Authorization header:

curl https://api.msgbubbles.com/v1/messages \
  -H "Authorization: Bearer sk_live_…"

API keys

  • Keys look like sk_live_… (production) or sk_test_… (test mode) and are issued during onboarding.
  • The plaintext key is shown exactly once. We store only a hash, so a lost key cannot be recovered — it can only be replaced.
  • Keep keys server-side. Never embed them in mobile apps or browser code; anyone holding the key can send messages as your numbers.

Auth errors

StatusMeaning
401 unauthorizedThe key is missing, malformed, unknown, or revoked.
403 forbiddenThe key is valid but the account is not active.

Account scoping

A valid key is necessary but not sufficient. Everything you can reach — messages, conversations, attachments, webhooks — is scoped to your account, and the from_handle on a send must be a number assigned or granted to you. Requests against another account’s resources return 404, never someone else’s data.

Your numbers

GET/v1/numbers

Lists the numbers your account can send from and what each can do — useful for rendering a from-number picker:

Response
{
  "data": [
    {
      "handle": "+18005551111",
      "channels": ["imessage", "sms", "whatsapp"],
      "label": null,
      "status": "online",
      "allocation": "dedicated"
    }
  ],
  "request_id": "req_…"
}

label is reserved for a display name and is currently always null — name your numbers in your own UI.

Dedicated and pooled numbers

Each organization has its own API key, conversations, attachments, and webhooks. A dedicated fleet line belongs to one organization. A pooled fleet line can be granted to several organizations. The numbers response includes allocation: dedicated or pooled. WhatsApp sessions remain specific to your account; WhatsApp pooling is not supported.

A successful send from a pooled line permanently reserves that line and recipient handle for your organization. Events for that conversation go only to your organization. If another organization already reserved the same pair, POST /v1/messages returns 409 pooled_recipient_conflict without queuing a message. Select another granted line from GET /v1/numbers and retry. Line selection is explicit; it is not automatic.

Pooled lines are send-only. Your messages go out, and you still get delivery receipts, read receipts, and failure events for them. Nothing a contact sends on a pooled line reaches you: no replies, attachments, reactions, or typing indicators. A contact can’t start a conversation on a pooled line, and group messaging isn’t supported there.

The one reply a pooled line acts on is an opt-out. When a contact you’ve messaged from a pooled line replies STOP, msgbubbles stops your messages to them, and START opts them back in.

If you need to receive replies, let contacts message you first, or use group messaging, use a dedicated line. The SMS sending limitations described in Messages apply on pooled lines too.

Revoking a shared-line grant stops new sends and is rechecked at queued dispatch, although a provider request already in flight may finish. The reservation and history remain yours, and a later STOP or START from that contact still applies to your organization. Reservations do not expire or transfer to another organization. Removing a grant does not revoke your API key or disable webhooks. Onboarding and grants are managed by the service operator.

Organizations share the physical line’s sending capacity and per-line pacing. Each organization also retains its per-key HTTP rate limit.

allocation is dedicatedfor a number that’s yours alone, or pooled for a shared number that other customers also send from. On a shared number, msgbubbles enforces opt-outs for you.

Switching from a pooled line to a dedicated one

Pooled lines are send-only, so to receive replies you need a dedicated line. The service operator assigns it, the same way it manages grants. Once it’s yours, it appears in GET /v1/numbers with "allocation": "dedicated". Then:

  • Send from the new number. Line selection is explicit, so your sends stay on the pooled line until you change from_handle. If you keep it in config, such as MSGBUBBLES_PHONE_NUMBER (see Configure your app), set it to the new number and redeploy.
  • Keep your API key and webhooks.Both belong to your organization, not to a line, so the key, webhook URL, and signing secret don’t change.
  • Subscribe to inbound events. On a dedicated line, replies, attachments, reactions, and typing indicators reach you, contacts can text you first, and you can use group messaging. An endpoint registered without an events list already receives everything. If you chose events while on the pooled line, add message.received and anything else you now want with PATCH /v1/webhooks/:id.
  • Handle opt-outs yourself. msgbubbles enforces opt-outs only on shared numbers. On your dedicated number, a STOP reply arrives as an ordinary message.received, and opt-outs recorded on your shared numbers don’t block sends from it. Carry your opt-out list over using the conversation.opted_out events you’ve already received.
  • Expect new threads. A conversation is a thread between one of your numbers and a contact, so your first send from the new number starts a new conversation. Your pooled-line conversations and their history stay in your account.

Monthly message allowances

Your administrator can set a monthly allowance such as 1,000 message operations. It is shared across all your organization’s keys, numbers, and channels. The window is a UTC calendar month, resetting at 00:00 UTC on the first day of the next month. Accounts default to unlimited.

GET/v1/usage

Use your own bearer key to read your allowance and current usage:

Usage response
{
  "data": {
    "monthly_limit": 1000,
    "used": 42,
    "remaining": 958,
    "period_start": "2026-10-01T00:00:00.000Z",
    "resets_at": "2026-11-01T00:00:00.000Z"
  },
  "request_id": "req_example"
}

Each accepted POST /v1/messages counts once, including sends that later fail delivery. Idempotent replays, automatic retries, and retrying an existing failed message do not count again. Inbound messages, reads, edits, reactions, typing and webhook deliveries do not count. Attachment count, text length and channel do not change the one-slot cost.

Group creation reserves one slot before attempting its opening message. That slot remains consumed if the sending operation times out or returns an error, because delivery may already have happened. A replay resolved before a new send attempt does not count again.

Exhaustion returns 429 monthly_quota_exceeded with Retry-After seconds until the reset. A quota-rejected send is not queued. Read access and inbound replies continue at the cap. Your administrator can raise the allowance or remove it; changing a limit or issuing another key does not clear usage. A zero limit blocks new sends; previously accepted messages and retries can still finish.

Unlimited accounts have monthly_limit: null and remaining: null; their future usage is still recorded. Counters start when the quota feature is deployed; earlier history is not backfilled. This allowance is independent of HTTP request limits and per-number pacing.

Rate limits and the error envelope are described in Errors & limits.