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 message to /messages with a recipient in the body. Sender routing is automatic unless you add an optional from string.

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",
 "text": "Hello!"
 }'

Try it

By default, v4 routes through the API key's configured priority. To pin the sender, pass one from string — a phone number, an alias, or a channel ID.

What changed at a glance

Area	v2	v4
Send	`POST /chats/{chatId}/messages` with `text`	`POST /messages` with `to`, top-level 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	top-level fields whose names identify the content (`text`, `attachments`, `poll`, …)
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, text } shape, adding from only when you need to pin 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 aliases, see Channels & senders.