Send a message on a specific channel
/channels/{channel}/messagesChannel-scoped equivalent of POST /messages with an explicit from: :channel accepts the same phone number (URL-encode + as %2B), alias, or ch_... value from accepts, and the body omits from. Multiple recipients on a group-capable channel (blooio/whatsapp) form a single group thread; on other channels they fan out to individual sends (max 100).
AuthorizationRequiredstringYour API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.
How to interpret text (and each parts[].text). Defaults to plain, which sends the string exactly as given.
With markdown, four constructs are parsed and delivered as real iMessage rich text — the recipient sees styled text, not delimiters:
| Construct | Syntax |
| --- | --- |
| Bold | **bold** or __bold__ |
| Italic | *italic* or _italic_ |
| Underline | ++underline++ |
| Strikethrough | ~~strike~~ |
They nest freely (**bold and _italic_**). Everything else Markdown can express — headings, lists, links, code spans, blockquotes, images — is NOT styling iMessage can carry, so it is passed through as literal characters: [Blooio](https://blooio.com) is delivered with its brackets and URL intact, and # Heading keeps its #. Escape a delimiter with a backslash (\*not italic\*) to send it literally.
The styling travels in the message's attributed body, so the stored text and the text returned on reads and webhooks is always the plain string the recipient sees, with the delimiters removed. The Markdown itself comes back as formatted_text, re-serialized into a normalized spelling rather than echoed verbatim (__bold__ returns as **bold**).
Only valid on Blooio iMessage channels — 422 format_unsupported_for_channel_type on any other channel type, since no other channel type has a rich-text equivalent and would otherwise deliver your delimiters as literal text. Rich text also requires the message to be delivered over iMessage: a Blooio send that falls back to SMS arrives as unstyled plain text (the text string), because SMS cannot carry styling.
Rejected with 422 invalid_content when set without text or parts, when the Markdown source exceeds 20000 characters, or when it compiles to more than 256 distinct formatting ranges.
"plain""markdown"Public https media URLs. May be combined with text. On Blooio iMessage, two or more image/video URLs are grouped into one photo/video carousel/collage bubble by default; set carousel: false to send them as separate bubbles. On RCS Business, a message takes one URL, and its files can total at most 5 MB (422 message_too_large); a URL that can't be downloaded returns 422 attachment_unavailable.
**Voice memos:** a single audio file (.mp3, .m4a, .wav, .aac, .opus, .ogg) is automatically sent as a voice memo (the native waveform/scrubber bubble), not a plain audio-file attachment — no extra field is needed. A voice memo is a standalone bubble, so it cannot be combined with text or any other attachment; do that and the send is rejected with 422 invalid_content. To send audio with a message, send the voice memo and the text as two separate requests.
A tappable rich link bubble (Blooio / Apple Messages for Business). On Apple Messages for Business, Blooio fills in whatever you leave out from the page's Open Graph tags (og:title, og:image, og:video) and converts the preview image to a PNG under Apple's 200 KB limit; a link whose image can't be brought under it is sent without one. Apple Maps, Apple Music, and App Clip URLs are built by Apple, so title and images are ignored for them. A text send that is only a URL is sent as a rich link too.
A tappable rich link bubble (Blooio / Apple Messages for Business). On Apple Messages for Business, Blooio fills in whatever you leave out from the page's Open Graph tags (og:title, og:image, og:video) and converts the preview image to a PNG under Apple's 200 KB limit; a link whose image can't be brought under it is sent without one. Apple Maps, Apple Music, and App Clip URLs are built by Apple, so title and images are ignored for them. A text send that is only a URL is sent as a rich link too.
An App Clip bubble (Blooio p2p iMessage only). Sends an App Clip launch URL that Messages renders as a native App Clip card (app icon + name + Open button); tapping it launches the instant App Clip experience without an install. Provide either a ready-made url (Apple's https://appclip.apple.com/id?p=<bundleID> launcher, or an app's own associated-domain App Clip link) or the bundle_id convenience field, which is expanded into the canonical Apple launch URL. Tip: App-Clip availability is region/OS gated by Apple; an unavailable clip renders a card that falls back to the App Store. To deep-link into an already-installed app instead (e.g. open a specific screen in a downloaded app), send that app's universal link via rich_link.
An App Clip bubble (Blooio p2p iMessage only). Sends an App Clip launch URL that Messages renders as a native App Clip card (app icon + name + Open button); tapping it launches the instant App Clip experience without an install. Provide either a ready-made url (Apple's https://appclip.apple.com/id?p=<bundleID> launcher, or an app's own associated-domain App Clip link) or the bundle_id convenience field, which is expanded into the canonical Apple launch URL. Tip: App-Clip availability is region/OS gated by Apple; an unavailable clip renders a card that falls back to the App Store. To deep-link into an already-installed app instead (e.g. open a specific screen in a downloaded app), send that app's universal link via rich_link.
Bring-your-own iMessage App Extension bubble (Blooio p2p iMessage only). Blooio is the transport, NOT the renderer: you point at YOUR OWN signed iMessage app extension and we assemble the MSMessage app balloon and send it. Recipients who have your app installed render its interactive overlay (its MSMessagesAppViewController reads url on tap); recipients who don't see the native template card (from caption/image_url) plus Apple's built-in App Store fallback. Identify your extension with bundle_id + team_id (used to form the com.apple.messages.MSMessageExtensionBalloonPlugin:<team_id>:<bundle_id> plugin id) and pass the app-state url your extension understands. This does NOT ship or host a renderer — the recipient must have your app for the interactive experience. (For instant, no-install experiences use app_clip; to deep-link into an already-installed app use rich_link.)
Bring-your-own iMessage App Extension bubble (Blooio p2p iMessage only). Blooio is the transport, NOT the renderer: you point at YOUR OWN signed iMessage app extension and we assemble the MSMessage app balloon and send it. Recipients who have your app installed render its interactive overlay (its MSMessagesAppViewController reads url on tap); recipients who don't see the native template card (from caption/image_url) plus Apple's built-in App Store fallback. Identify your extension with bundle_id + team_id (used to form the com.apple.messages.MSMessageExtensionBalloonPlugin:<team_id>:<bundle_id> plugin id) and pass the app-state url your extension understands. This does NOT ship or host a renderer — the recipient must have your app for the interactive experience. (For instant, no-install experiences use app_clip; to deep-link into an already-installed app use rich_link.)
An iMessage sticker (Blooio p2p iMessage only), sent on its own or placed on a message the way you drag a sticker onto a bubble in Messages. The file is sent unchanged: a PNG, APNG, GIF, HEIC or HEICS (animated HEIC) image, at most 40 MB (41,943,040 bytes). Transparent PNGs and HEICS keep their transparency and animation. A sticker can't carry text or be a reply_to; place it with placed_on instead. The file is checked when the message is sent, so a file that is too large fails the message with message_too_large and one that isn't a sticker format with invalid_content. Field errors are 422 invalid_sticker; a placed_on that can't take a sticker is 404 sticker_target_not_found, 409 sticker_target_not_reactable (not sent yet) or 400 sticker_target_expired (older than 30 days). Dashboard users can upload a file to POST /v4/dashboard/stickers for its URL.
An iMessage sticker (Blooio p2p iMessage only), sent on its own or placed on a message the way you drag a sticker onto a bubble in Messages. The file is sent unchanged: a PNG, APNG, GIF, HEIC or HEICS (animated HEIC) image, at most 40 MB (41,943,040 bytes). Transparent PNGs and HEICS keep their transparency and animation. A sticker can't carry text or be a reply_to; place it with placed_on instead. The file is checked when the message is sent, so a file that is too large fails the message with message_too_large and one that isn't a sticker format with invalid_content. Field errors are 422 invalid_sticker; a placed_on that can't take a sticker is 404 sticker_target_not_found, 409 sticker_target_not_reactable (not sent yet) or 400 sticker_target_expired (older than 30 days). Dashboard users can upload a file to POST /v4/dashboard/stickers for its URL.
Interactive content. On Apple Messages for Business this renders as a native interactive message: a quick reply, list picker, time picker, dynamic form, Apple Pay request, authentication (Sign in) request, or a custom iMessage app. Select the variant with kind and populate that kind's required fields; fields not relevant to the chosen kind are ignored. Each kind is validated against the minimum shape Apple needs to render it BEFORE the message is sent: Apple's gateway accepts malformed payloads and then shows an empty bubble on device, so Blooio rejects them up front with a 422 and a kind-specific code (invalid_quick_reply, invalid_list_picker, invalid_time_picker, invalid_form, invalid_apple_pay, invalid_authenticate, invalid_imessage_app) whose message names the exact field/index that is wrong. Free-form objects (dynamic, payment, authenticate) are otherwise forwarded to Apple verbatim. Before sending, the chosen kind is also checked against the device capability-list Apple stamps on the conversation's latest inbound message: when a list is known and does not advertise the required capability, the send is rejected with 422 amb_capability_unavailable (naming the missing Apple capability) rather than delivering a bubble the device can't render. On Blooio RCS only quick_reply is supported: summary_text is sent as text with each item as a reply chip (at most 11, titles up to 25 characters), and other kinds return 422 interactive_kind_unsupported_for_channel_type.
Interactive content. On Apple Messages for Business this renders as a native interactive message: a quick reply, list picker, time picker, dynamic form, Apple Pay request, authentication (Sign in) request, or a custom iMessage app. Select the variant with kind and populate that kind's required fields; fields not relevant to the chosen kind are ignored. Each kind is validated against the minimum shape Apple needs to render it BEFORE the message is sent: Apple's gateway accepts malformed payloads and then shows an empty bubble on device, so Blooio rejects them up front with a 422 and a kind-specific code (invalid_quick_reply, invalid_list_picker, invalid_time_picker, invalid_form, invalid_apple_pay, invalid_authenticate, invalid_imessage_app) whose message names the exact field/index that is wrong. Free-form objects (dynamic, payment, authenticate) are otherwise forwarded to Apple verbatim. Before sending, the chosen kind is also checked against the device capability-list Apple stamps on the conversation's latest inbound message: when a list is known and does not advertise the required capability, the send is rejected with 422 amb_capability_unavailable (naming the missing Apple capability) rather than delivering a bubble the device can't render. On Blooio RCS only quick_reply is supported: summary_text is sent as text with each item as a reply chip (at most 11, titles up to 25 characters), and other kinds return 422 interactive_kind_unsupported_for_channel_type.
Inline PNG assets referenced by imageIdentifier elsewhere in the payload. Supply each as base64 data OR a url (fetched server-side, and converted to a PNG within 200 KB when it isn't one). Every image — fetched or inline — is validated from its MAGIC BYTES (not the Content-Type): it must be a real PNG (422 amb_image_not_png / code on the failed send otherwise), within Apple's 200 KB per-image cap (amb_image_too_large) and 5 MB aggregate cap (amb_images_total_too_large), and within the @3x dimension ceiling — supply expected_size: { width, height, style } to enforce an exact @3x size, rejected with amb_image_bad_dimensions naming the expected size. When the resulting interactiveData would exceed Apple's ~10 KB inline ceiling, Blooio automatically uploads it and sends it by interactiveDataRef instead (Apple's 200 on an over-limit inline payload is not treated as conformance).
Inline PNG assets referenced by imageIdentifier elsewhere in the payload. Supply each as base64 data OR a url (fetched server-side, and converted to a PNG within 200 KB when it isn't one). Every image — fetched or inline — is validated from its MAGIC BYTES (not the Content-Type): it must be a real PNG (422 amb_image_not_png / code on the failed send otherwise), within Apple's 200 KB per-image cap (amb_image_too_large) and 5 MB aggregate cap (amb_images_total_too_large), and within the @3x dimension ceiling — supply expected_size: { width, height, style } to enforce an exact @3x size, rejected with amb_image_bad_dimensions naming the expected size. When the resulting interactiveData would exceed Apple's ~10 KB inline ceiling, Blooio automatically uploads it and sends it by interactiveDataRef instead (Apple's 200 on an over-limit inline payload is not treated as conformance).
Array of object
List picker sections (kind = list_picker). Required: at least one section, each with a non-empty title and at least one item; every item needs a non-empty identifier and title. Rejected with 422 invalid_list_picker otherwise. Blooio normalizes the input into Apple's reliably-rendering wire shape (listPicker.sections[].items[] with a per-item style, under a live-layout envelope) — the shape confirmed to both render the bubble and populate options on tap. May also be supplied as list (an array of sections or an object with a sections array).
List picker sections (kind = list_picker). Required: at least one section, each with a non-empty title and at least one item; every item needs a non-empty identifier and title. Rejected with 422 invalid_list_picker otherwise. Blooio normalizes the input into Apple's reliably-rendering wire shape (listPicker.sections[].items[] with a per-item style, under a live-layout envelope) — the shape confirmed to both render the bubble and populate options on tap. May also be supplied as list (an array of sections or an object with a sections array).
Array of object
Apple dynamic interactive message (multi-page form) object, forwarded verbatim (kind = form). Required: at least one page under pages (or data.pages); also carries startPageIdentifier, requestIdentifier, showSummary, etc. Rejected with 422 invalid_form otherwise. May also be supplied under form.
Apple Pay payment request object, forwarded verbatim (kind = apple_pay). Required: a paymentRequest object with total (label + numeric amount), currencyCode (ISO-4217), and countryCode (ISO-3166). Rejected with 422 invalid_apple_pay otherwise. Apple additionally gates delivery on the merchant configuration.
Apple Messages for Business invitation. Sends an Apple-managed notification template (Live Layout) that invites the customer into a business chat. Addressed to a phone number (tel:+E164) rather than an opaque Apple Messages for Business id. Requires prior Invitations approval from Apple and explicit customer opt-in.
Apple Messages for Business invitation. Sends an Apple-managed notification template (Live Layout) that invites the customer into a business chat. Addressed to a phone number (tel:+E164) rather than an opaque Apple Messages for Business id. Requires prior Invitations approval from Apple and explicit customer opt-in.
Template parameter values required by the chosen template (e.g. brandName, and brandLogo as a base64 PNG). For known templates the required parameters are enforced before sending — e.g. binaryChoice.engage.withImage requires brandName + brandLogo — and a missing one is rejected with 422 invalid_invitation naming the field (rather than being accepted and then rejected by Apple with 400 Invalid payload).
Ordered text/media parts sent as one multipart message (Blooio only). When every part is an image/video (two or more, no text parts) Messages renders them as a photo/video carousel/collage by default; set carousel: false to opt out. With format: "markdown", each part's text is parsed for styling independently.
Ordered text/media parts sent as one multipart message (Blooio only). When every part is an image/video (two or more, no text parts) Messages renders them as a photo/video carousel/collage by default; set carousel: false to opt out. With format: "markdown", each part's text is parsed for styling independently.
Optional attribution badge shown under the bubble: sent_with_siri renders "Sent with Siri" and sent_with_facetime renders "Sent with FaceTime", the way a message dictated to Siri or sent during a FaceTime call appears. Omit for no badge. Any other value is rejected with 422 invalid_content. Applies to text, attachments (media), parts (multipart), rich_link, and app_clip sends on Blooio iMessage channels only; rejected with 422 invalid_content on other content types. No effect on non-Blooio channels.
"sent_with_siri""sent_with_facetime"Group image/video attachments into ONE message that Messages renders as a swipeable photo/video carousel/collage, instead of separate bubbles (Blooio p2p iMessage only). DEFAULTS ON: a Blooio send whose attachments (via attachments or parts) are two or more image/video URLs is grouped automatically — set carousel: false to send them as independent bubbles instead. Set carousel: true explicitly to also enforce the visual-only rule (a known non-visual extension like .pdf, a text part, or fewer than two attachments then returns 422 invalid_carousel); left unset, a non-qualifying send simply isn't grouped. Image extensions: jpg/jpeg/png/gif/heic/heif/webp/bmp/tiff/avif; video: mov/mp4/m4v/qt/3gp/avi/mkv/webm; a URL with no extension is allowed (its real type resolves on the device). An optional text is carried as the carousel's caption. Only valid on Blooio iMessage channels (422 carousel_unsupported_for_channel_type if set on another channel type).
Array of RcsCard
Array of RcsSuggestion
Array of RcsSuggestion
What to do when the recipient's device can't show interactive, rich_card, or suggestions content. reject (the default) fails the send with a 422 naming what's missing (amb_capability_unavailable on Apple Messages for Business, rcs_feature_unsupported with missing_features on Blooio RCS). auto sends the closest thing the device can show instead: on Blooio RCS, cards and chips it can't show become text and links. The force-fallback header sets auto too.
"reject""auto"A recipient: a raw identifier string (phone/email/opaque provider id), an array of identifier strings (multiple recipients), an existing { group_id } with an exact sender, or (for routed sends) a { contact_id }. A contact_id enables cross-channel-type routing via the contact's identities; a bare identifier reaches phone/email-addressable channels only.
A recipient: a raw identifier string (phone/email/opaque provider id), an array of identifier strings (multiple recipients), an existing { group_id } with an exact sender, or (for routed sends) a { contact_id }. A contact_id enables cross-channel-type routing via the contact's identities; a bare identifier reaches phone/email-addressable channels only.
Transport state or resolved wire service; never null. pending = accepted and dispatched, wire service not resolved yet; imessage / rcs / sms = the device-confirmed transport (iMessage blue bubble, RCS, or SMS/MMS green bubble); whatsapp = sent over P2P WhatsApp; whatsapp_business = sent over the WhatsApp Business Platform (WABA); rcs_business = sent over Blooio RCS, from a verified RCS business sender; amb = sent over Apple Messages for Business; unknown = accepted but the transport could not be resolved before the tracking window closed (see error).
"pending""unknown""imessage""sms""rcs""whatsapp""whatsapp_business""rcs_business""amb"Initial lifecycle state for the send: normally queued (accepted for delivery), pending when the message waits behind the channel's opener (see routing.opener), or failed if rejected before dispatch. Later transitions (sent → delivered / read, or failed) are reported via the message status endpoint and message.* webhooks.
Why this channel was tried (priority mode): last_inbound / last_outbound = the contact's most recent conversation was on it; claim = the pool number the contact was first sent from; switch_number = their number was banned and they were moved to another in the pool; priority = the priority's step order.
"priority""last_inbound""last_outbound""claim""switch_number"Array of RoutingAttempt
Present when the message waits behind the channel's opener: an Apple Messages for Business invitation, or a WhatsApp Business template outside the contact's 24-hour window. The message reports pending until the contact answers, then goes out in order with the messages sent to them since, or fails (message.failed, amb_invitation_declined) if they decline the invitation. A dry run has no message_id. See the channel's opener setting.
Present when the message waits behind the channel's opener: an Apple Messages for Business invitation, or a WhatsApp Business template outside the contact's 24-hour window. The message reports pending until the contact answers, then goes out in order with the messages sent to them since, or fails (message.failed, amb_invitation_declined) if they decline the invitation. A dry run has no message_id. See the channel's opener setting.
Sends a live request with your values and shows the real response below. Your key is stored only in this browser.
curl -X POST https://api.blooio.com/v4/channels/string/messages \{ "id": "obj_a1b2c3d4", "chat_id": "chat_a1b2c3d4", "channel_id": "ch_a1b2c3d4", "channel_type": "blooio", "protocol": "pending", "from": "+15551234567", "direction": "inbound", "type": "string", "status": "active", "group_id": "grp_a1b2c3d4", "error": { "code": null, "message": "Hello from Blooio!" }, "fallback": { "recommended": false, "reason": "string" }, "downgraded_from": "string", "to": "+15551234567", "dry_run": false, "would_send": false, "preview": {}, "poll": { "title": "Example title", "options": [ "string" ] }, "routing": { "mode": "explicit", "channel_type": "blooio", "number": "+15551234567", "alias": "string", "priority_id": "obj_a1b2c3d4", "priority": 0, "source": "priority", "fallthrough": [ { "channel_id": "ch_a1b2c3d4", "channel_type": "blooio", "outcome": "skipped", "code": "string", "message": "Hello from Blooio!" } ], "transition": { "mode": "pre", "message_id": "msg_a1b2c3d4", "error": { "code": "string", "message": "Hello from Blooio!" } }, "opener": { "type": "invitation", "message_id": "msg_a1b2c3d4" } }}