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

Channels & senders

How v4 chooses who you send from — channels, aliases, and the scalar from value.

This guide explains who you send from in the v4 API: channels, aliases, and when to use each form of from.

The vocabulary

Term Meaning Examples
Channel One configured sender — a Blooio number, Twilio number, WhatsApp session, or RCS agent ch_... with address +15551230001
Channel type The adapter family a channel belongs to blooio, twilio, amb, rcs_business
Alias A movable name for a non-numbered channel support, sales-us
Priority An ordered list of channels used for automatic routing the Channels board in the dashboard

Configure which channels each API key can use on the Channels page in the dashboard. Order in that list is send priority — the top channel is tried first.

The default: omit from

Most sends should look like this:

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

When from is omitted, Blooio picks a channel from the API key's configured priority (and hybrid outbound, when enabled). You do not need to look up a ch_... id for everyday sends.

Use this when: you want Blooio to route for you, and your Channels priority is already set up.

The from string

from is one optional string. It accepts a phone number, alias, or channel ID — the value you already know:

Goal from value Example
Let Blooio choose Omit from { "to": "...", "text": "..." }
Exact phone number The number (E.164) "from": "+15551230001"
Named RCS sender The alias "from": "support"
Exact technical channel The channel ID "from": "ch_..."

Resolution order is: ch_... → exact channel; valid phone number → exact numbered channel; anything else → organization-wide alias.

Separate top-level fields control automatic routing and are mutually exclusive with an explicit from:

  • "priority_id": "priority_..." — walk a specific priority list.
  • "channel_type": "blooio" — constrain automatic/priority routing to one channel type.

Exact number

Use when a specific phone line must send:

{
 "from": "+15551230001",
 "to": "+15551234567",
 "text": "Sent from our LA number"
}

Pass E.164 (+1...). If a number ever matched active channels of more than one type, the send returns 409 ambiguous_from with the candidates — use the exact ch_... value instead.

Use this when: branding, compliance, or sticky routing requires one known line.

Alias

Non-numbered channels (RCS Business) do not have a phone number. They use an alias — a short stable name you choose in the dashboard.

{
 "from": "support",
 "to": "+15551234567",
 "text": "How can we help?"
}

Rules for aliases:

  • 2–64 characters
  • Lowercase letters, numbers, hyphens, underscores
  • Must start with a letter
  • Unique per organization
  • Cannot start with a reserved ID prefix such as ch_ or msg_

If you leave the alias blank when connecting a non-numbered channel, Blooio generates one. You can rename it later, or transfer an existing alias onto a replacement channel so your API payloads keep working.

Use this when: you send through RCS Business and want a readable name instead of a technical ch_... id. Prefer aliases over ids in application code — aliases survive replacing the underlying integration.

Exact channel ID

{
 "from": "ch_019ec226-97d0-7fd8-b08a-495be0369449",
 "to": "+15551234567",
 "text": "Advanced pin"
}

Use this when: an internal tool already stores channel_id, or you are debugging. For product code, prefer the number or alias.

Channel-scoped sends

POST /v4/channels/{channel}/messages is the channel-scoped equivalent of passing from: the path accepts the same phone number (URL-encode + as %2B), alias, or ch_... value, and the body omits from:

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

New message vs reply

Situation Endpoint
Start or continue by recipient POST /messages with to (+ optional from)
Reply inside a known chat POST /chats/{chatId}/messages

Chat replies inherit the chat's channel; you do not pass from there.

Polls

Polls are normal message content on Blooio. Route them like any other send — usually with "channel_type": "blooio" so only poll-capable channels are considered:

{
 "channel_type": "blooio",
 "to": "+15551234567",
 "poll": {
 "title": "Which day works?",
 "options": ["Monday", "Wednesday", "Friday"]
 }
}

Dedicated chat poll endpoints remain available for compatibility.

What the response tells you

Successful sends return the resolved from (the human value — number or alias), the exact channel, and a routing object:

{
 "id": "msg_...",
 "chat_id": "chat_...",
 "from": "+15551230001",
 "channel_id": "ch_...",
 "channel_type": "blooio",
 "status": "queued",
 "routing": {
 "mode": "priority",
 "channel_type": "blooio",
 "priority_id": "priority_...",
 "priority": 1
 }
}
  • mode: "explicit" — you pinned the sender with from
  • mode: "priority" / hybrid — Blooio selected from your configured list

List channels with GET /channels. Numbered channels expose their phone number as address; non-numbered channels also return their alias.

Dashboard checklist

  1. Open Channels in the dashboard.
  2. Drag channels onto the API key or integration that should use them.
  3. Order matters when there is more than one channel — top is tried first.
  4. For non-numbered channels, click the key icon to rename or transfer the alias.
  5. Enable Hybrid mode only when you want Twilio-first outreach that can continue on Blooio after a reply.

Common mistakes

Mistake Fix
Passing from as an object from is one string: a phone number, alias, or channel ID
Combining from with priority_id / channel_type They are mutually exclusive — pick one routing intent
Hard-coding ch_... in app code Prefer the number or alias
Expecting an alias to work without assigning the channel Assign the channel to the API key on the Channels page