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

Attachments

Send images, videos, and files with v4 media content.

In v4, attachments are a top-level attachments array of public URLs; add text for an optional caption.

How a media send is fetched, prepared, and delivered. Click a step for details.

Send media

curl -X POST https://api.blooio.com/v4/messages \
 -H "Authorization: Bearer bl_live_..." \
 -H "Content-Type: application/json" \
 -d '{
 "to": "+15551234567",
 "text": "Here is the file",
 "attachments": ["https://cdn.example.com/invoice.pdf"]
 }'
Try it

URLs must be publicly reachable over HTTPS. Common formats include images (JPEG, PNG, GIF, HEIC), video, audio, and PDFs — exact support depends on the channel.

Tips

  • Prefer stable CDN URLs; ephemeral signed URLs can expire before the device downloads them.
  • Keep files reasonably sized for mobile delivery.
  • For iMessage-only media behavior, constrain with "channel_type": "blooio".
  • Caption text is optional alongside attachments.

Carousels

Two or more image/video attachments are grouped into a single carousel automatically on Blooio iMessage — no flag needed. An optional top-level text becomes the caption:

{
 "to": "+15551234567",
 "text": "Here are the photos!",
 "attachments": [
 "https://cdn.example.com/photo1.jpg",
 "https://cdn.example.com/photo2.png"
 ]
}

Set "carousel": false to send each attachment as its own bubble instead. Setting "carousel": true explicitly additionally enforces the visual-only rule, so a non-image/video attachment or a text part then returns 422 invalid_carousel instead of being left ungrouped. Grouping is Blooio iMessage only — carousel: true on another channel type returns 422 carousel_unsupported_for_channel_type.

Send Result
2+ image/video URLs (nothing set) Grouped into one carousel automatically
2+ image/video URLs, carousel: false Sent as separate bubbles
A single attachment + carousel: true 422 invalid_carousel
A non-visual attachment (.pdf, .zip) + carousel: true 422 invalid_carousel
carousel: true on a non-media send 422 invalid_content

When a recipient reacts to one image in a carousel, the message.reaction webhook includes part_index (the 0-based bubble) and reacted_attachment ({ index, url, media_type, size, caption }, or null when the tapback landed on the caption).

Attribution badge

Set the optional badge field to show an attribution line under an iMessage 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 it for no badge; any other value returns 422 invalid_content. It works on text, attachments, parts, rich_link, and app_clip sends:

{
 "to": "+15551234567",
 "text": "On my way!",
 "badge": "sent_with_siri"
}

It's Blooio iMessage only; setting it on any other content type returns 422 invalid_content.