Priorities

Ordered sender lists per API key — default routing, tiers, pools, and from.priority_id.

A priority is an ordered list of channels (senders) owned by an API key. When you omit an exact from selector on POST /messages, Blooio walks a priority to choose who sends.

The Channels board in the dashboard is the UI for the key's default priority. The API exposes the same model under /priorities.

How it relates to pools and hybrid

Concept	Role
Number pools	The phone senders in a priority (same-type tiers act as sticky pools)
Priority	The ordered waterfall + which list is the key's default
Hybrid mode	Special Twilio→Blooio routing that runs before normal priority walk when enabled

Default vs named priorities

Each API key can have one default priority (is_default: true). Agnostic sends use it automatically:

Explicit from.priority_id (or legacy top-level priority_id)
Else the key's default priority
Else an implicit Blooio pool of numbers owned by the key (zero-config fallback)

Inspect the default:

curl https://api.blooio.com/v4/me/priority \
  -H "Authorization: Bearer bl_live_..."

Try it

Tiers and same-type pools

Each entry in a priority has a tier number (priority: 1, 2, 3…). Lower tiers run first.

Different tiers — waterfall (try tier 1, then tier 2, …).
Same tier + same channel type — a pool. Blooio picks within the pool using history-first stickiness (especially for Blooio numbers).

priority_sales (default)
  tier 1  blooio  +15551110001  ┐
  tier 1  blooio  +15551110002  ┘  pool (sticky)
  tier 2  twilio  +15552220001     fallback type

Selection is history-first: if the contact already has history on a higher-priority addressable tier, that tier wins; otherwise Blooio cold-starts on the best addressable tier.

Create and update via API

curl -X POST https://api.blooio.com/v4/priorities \
  -H "Authorization: Bearer bl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "is_default": true,
    "channels": [
      "ch_blooio_1",
      "ch_blooio_2",
      { "channel_id": "ch_twilio_1", "priority": 2 }
    ]
  }'

Try it

Passing bare channel id strings assigns ascending tiers in order. Objects let you set the tier explicitly. Same-tier channels must share a channel type.

Most teams never call this — they drag senders on the Channels page, which persists the default priority.

Send with an explicit priority

{
  "from": { "priority_id": "priority_..." },
  "to": "+15551234567",
  "content": { "type": "text", "text": "Hello" }
}

Combine with a type filter:

{ "from": { "type": "blooio", "priority_id": "priority_..." } }

Exact selectors (from.number, from.sender_key, from.id) bypass priority walking and pin one sender.

When to use what

Goal	Approach
Everyday send	Omit `from`; configure default priority in the dashboard
Only iMessage / only SMS	`from.type` (still walks the default priority filtered by type)
A second routing list (e.g. marketing vs support)	Named priority + `from.priority_id`
Always this number	`from.type` + `from.number`