Migrating from v2 to v4

The v4 API is the current generation of the Blooio API. It introduces a unified, multi-channel message model, cursor-based pagination, and a structured error envelope. The v2 API remains fully supported for backwards compatibility — you can migrate endpoint by endpoint at your own pace.

Both versions are live. v2 requests keep working; new features land in v4 first.

Base URL

Version	Base URL
v4	`https://api.blooio.com/v4`
v2	`https://api.blooio.com/v2/api`

Authentication is unchanged — send your key as a bearer token (Authorization: Bearer bl_live_...) in both versions.

Sending a message

The biggest change is the send model. v2 posts text to a chat addressed by a URL-encoded identifier. v4 posts a structured message to /messages with a recipient and typed content. Sender routing is automatic unless you add an optional from selector.

curl -X POST https://api.blooio.com/v2/api/chats/%2B15551234567/messages \
  -H "Authorization: Bearer bl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello!" }'

Try it

curl -X POST https://api.blooio.com/v4/messages \
  -H "Authorization: Bearer bl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "content": { "type": "text", "text": "Hello!" }
  }'

Try it

By default, v4 routes through the API key's configured priority. Use from.type to constrain the channel type, from.number for an exact phone-number sender, or from.sender_key for a non-numbered RCS Business sender.

What changed at a glance

Area	v2	v4
Send	`POST /chats/{chatId}/messages` with `text`	`POST /messages` with `to`, `content`, and optional `from`
Addressing	URL-encoded identifier in the path	recipient in the body; sender selected automatically or with `from`
Content	`text` / `attachments` fields	typed `content` (`text`, attachments, etc.)
Pagination	`limit` / `offset`	cursor-based (`cursor`, `has_more`, `next_cursor`)
Errors	`{ error, message, status }`	`{ "error": { code, message, details } }`

See Pagination and Errors for the v4 conventions in detail.

Migration checklist

Configure sender priority in the Channels dashboard. Most sends require no channel lookup.
Switch the base URL to /v4 for the endpoints you're moving.
Update your send payloads to the { to, content } shape, adding from only when you need to constrain or select the sender.
Update pagination from offset to cursor loops (next_cursor → cursor).
Update error handling to branch on error.code instead of the flat error string.
Re-point webhooks — v4 events use a structured envelope (see Webhooks).

You don't have to migrate everything at once. Run v2 and v4 side by side and cut endpoints over individually.

For a deeper walkthrough of channels, senders, from, and sender_key, see Channels & senders.