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 an explicit channel_id, recipient, and typed content.

v2

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!" }'

v4

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

In v4 you select a channel (a sending surface such as an iMessage number) explicitly with channel_id rather than relying on implicit number-pool selection. List channels with GET /channels.

What changed at a glance

Area	v2	v4
Send	POST /chats/{chatId}/messages with text	POST /messages with channel_id, to, content
Addressing	URL-encoded identifier in the path	channel_id + to.identifier in the body
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

1. Provision channels. Call GET /channels and store the channel_id(s) you'll send from.
2. Switch the base URL to /v4 for the endpoints you're moving.
3. Update your send payloads to the { channel_id, to, content } shape.
4. Update pagination from offset to cursor loops (next_cursor → cursor).
5. Update error handling to branch on error.code instead of the flat error string.
6. 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.