Channels & senders

This guide explains who you send from in the v4 API: channels, senders, sender keys, and when to use each from option.

The vocabulary

Configure which senders each API key can use on the Channels page in the dashboard. Order in that list is send priority — the top sender 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",
    "content": { "type": "text", "text": "Hello!" }
  }'

When from is omitted, Blooio picks a sender 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.

Choosing a send option

Add an optional from object only when you need to constrain or pin the sender.

You can combine type with priority_id to walk that priority list filtered to one channel type. Do not combine conflicting exact selectors (for example number and sender_key together).

Legacy top-level channel_id and priority_id still work, but prefer from.

Option details

Constrain by channel type

Use when any Blooio (or Twilio, etc.) sender is fine, but you do not want another channel type to win:

{
  "from": { "type": "blooio" },
  "to": "+15551234567",
  "content": { "type": "text", "text": "Hello from iMessage" }
}

Blooio still walks your priority among senders of that type.

Use this when: the product must stay on one transport (e.g. iMessage-only features like polls or effects).

Exact number

Use when a specific phone line must send:

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

number requires a numbered channel type: blooio, twilio, whatsapp, or whatsapp_business. Pass E.164 (+1...).

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

Exact sender_key

Non-numbered business channels (today AMB and RCS Business) do not have a phone number. They use a sender key — a short stable name you choose in the dashboard.

{
  "from": { "type": "amb", "sender_key": "support" },
  "to": { "identifier": "opaque-amb-customer-id" },
  "content": { "type": "text", "text": "How can we help?" }
}

Rules for sender_key:

• 2–64 characters
• Lowercase letters, numbers, hyphens, underscores
• Must start with a letter
• Unique per organization + channel type

If you leave the key blank when connecting AMB, Blooio generates one. You can rename it later, or transfer an existing key onto a replacement integration so your API payloads keep working.

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

Exact channel id

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

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

New message vs reply

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

Polls

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

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

Dedicated chat poll endpoints remain available for compatibility.

What the response tells you

Successful sends include the resolved channel and a routing object, for example:

{
  "id": "msg_...",
  "chat_id": "chat_...",
  "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 (number, sender_key, or id)
• mode: "priority" / hybrid — Blooio selected from your configured list

List channels with GET /channels. Numbered senders expose their phone number as display_address; keyed senders also return sender_key.

Dashboard checklist

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

Common mistakes

Related

• Quickstart — send your first v4 message
• Priorities — default routing lists and from.priority_id
• Chats — opaque chat_ threads
• Message sending
• Number pools
• Hybrid mode
• Twilio integration
• Migrating from v2 to v4 — endpoint and payload differences
• Send a message — full request schema
• List channels — inspect senders and keys