BetaThe V4 API is in beta — endpoints and functionality may change.
Messagesv4

Send a message

POST/messages

The primary endpoint for starting a message. from is optional: 1. Automatic — omit from to use hybrid/default-priority/implicit Blooio routing. 2. Hybrid owner{ "from": { "type": "hybrid", "number": "+15551234567" } } uses the uniquely resolved, hybrid-enabled owner of that representative number for a one-to-one phone send or an existing group owned by that hybrid sender. 3. Channel type{ "from": { "type": "blooio" } } walks the priority using only that type. 4. Natural number{ "from": { "type": "blooio", "number": "+15551234567" } } selects an exact numbered sender. 5. Sender key{ "from": { "type": "rcs_business", "sender_key": "support" } } selects an exact non-numbered sender. 6. Technical id{ "from": { "id": "ch_..." } } is the advanced exact-channel form. Type/priority routing is history-first and content-aware. Poll content currently routes only through Blooio. Existing groups require an exact sender whose channel owns the group or a hybrid sender that owns that channel. Legacy top-level channel_id and priority_id remain supported. Returns the chosen channel_id, chat_id, and routing explanation.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer
Idempotency-Keyoptionalstring

Optional key for safe retries. Replaying the same key with an identical body returns the original result; a different body returns 409. Use a unique value (such as a UUID) per logical request.

Body parameters

JSON
fromoptionalSenderSelector

Optional sender selection. Omit it for automatic routing. Exact selectors bypass priority routing.

idRequiredstring

Exact technical channel id (ch_...).

channel_idoptionalstring

Legacy exact-channel selector. Prefer from.id.

priority_idoptionalstring

Legacy priority selector. Prefer from.priority_id.

toRequiredRecipient

A recipient: a single identifier, a list, a comma-separated string, an existing { group_id } with an exact or hybrid owner sender, or (for routed sends) a { contact_id }. A contact_id enables cross-channel-type routing via the contact's identities; a bare identifier reaches phone/email-addressable channels only.

identifierRequiredstring
typeoptionalstring

Optional advisory address-kind hint. Routing infers the address kind from the identifier and channel, so this value does not change delivery.

contentRequiredMessageContent
typeRequired"text"
textRequiredstring
reply_tooptionalstring

Message id to reply to.

effectoptionalstring

iMessage screen/bubble effect (Blooio).

link_previewoptionalLinkPreview
imageUrloptionalstring
titleoptionalstring
dry_runoptionalboolean

Validate and route only; do not send.

Returns

idoptionalstring
chat_idoptionalstring
channel_idoptionalstring
channel_typeoptionalstring
"blooio""twilio""whatsapp""whatsapp_business""rcs_business"
protocoloptionalstring

Transport state or resolved wire service; never null. pending = accepted and dispatched, wire service not resolved yet; imessage / rcs / sms = the device-confirmed transport (iMessage blue bubble, RCS, or SMS/MMS green bubble); whatsapp = sent over WhatsApp; unknown = accepted but the transport could not be resolved before the tracking window closed (see error).

"pending""unknown""imessage""sms""rcs""whatsapp"
directionoptionalstring
"inbound""outbound"
typeoptionalstring
statusoptionalstring

Initial lifecycle state for the send: normally queued (accepted for delivery), or failed if rejected before dispatch. Later transitions (sentdelivered / read, or failed) are reported via the message status endpoint and message.* webhooks.

group_idoptionalstring

Existing group id for a group-targeted send.

hybridoptionalobject

Hybrid routing phase and optional transition placement.

erroroptionalobject | null
fallbackoptionalobject

Present when a send could not be delivered on the requested channel and a different channel should be tried.

recommendedoptionalboolean

True when falling back to another channel is recommended.

reasonoptionalstring
tooptionalstring

Recipient identifier. Present only on per-recipient items inside a fan-out (FanOutResult) response.

dry_runoptionalboolean
would_sendoptionalboolean
previewoptionalobject
polloptionalobject
titleoptionalstring
optionsoptionalstring[]
routingoptionalRoutingMetadata

How Blooio selected the concrete sender channel.

modeoptionalstring
"explicit""priority""hybrid"
channel_typeoptionalstring
"blooio""twilio""whatsapp""whatsapp_business""rcs_business"
numberoptionalstring
sender_keyoptionalstring
priority_idoptionalstring
priorityoptionalinteger

Response codes

200Dry-run preview
201Message accepted. The message object is returned with its current `status`; a synchronously rejected send returns `status: "failed"` with an `error` object (still 201, since the message was created).
207Multi-recipient fan-out with mixed results (some recipients sent, some failed). See per-recipient items in `data`.
401Your API key is missing or invalid. Pass it as a bearer token.
404No message was found.
409The request conflicts with the current state of the message (e.g. it already exists, the chat is closed, or the channel isn't active).
422Validation failed, or a multi-recipient fan-out in which every recipient failed (in which case the body is a `FanOutResult` rather than an error envelope).
501This message endpoint is defined but not implemented yet.

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request
curl -X POST https://api.blooio.com/v4/messages \
Body object
Response objectexample
{  "id": "obj_a1b2c3d4",  "chat_id": "chat_a1b2c3d4",  "channel_id": "ch_a1b2c3d4",  "channel_type": "blooio",  "protocol": "pending",  "direction": "inbound",  "type": "string",  "status": "active",  "group_id": "grp_a1b2c3d4",  "hybrid": {},  "error": {},  "fallback": {    "recommended": false,    "reason": "string"  },  "to": "+15551234567",  "dry_run": false,  "would_send": false,  "preview": {},  "poll": {    "title": "Example title",    "options": [      "string"    ]  },  "routing": {    "mode": "explicit",    "channel_type": "blooio",    "number": "+15551234567",    "sender_key": "string",    "priority_id": "obj_a1b2c3d4",    "priority": 0  }}