Blooio API Reference

Authentication and account information

Manage phone numbers linked to your account

Manage and share your iMessage contact card (Name & Photo)

Manage contacts (phone numbers and emails)

Manage contact groups

Manage group membership

Manage webhook subscriptions

View and replay webhook deliveries

View conversations and messages

View individual messages and their status

Control typing indicators for conversations

Mark conversations as read

Add or remove reactions to messages. Supports classic iMessage tapbacks (love, like, dislike, laugh, emphasize, question) and emoji reactions (e.g. +😂, -😂).

Send native iMessage polls and retrieve poll results with vote counts. Poll events are delivered via separate webhook event types (poll.received, poll.created, poll.voted) and require webhook_type 'poll' or 'all'.

FindMy contact location tracking

Initiate FaceTime calls

Phone number validation, formatting, and NANPA geocoding. Requires an Enterprise plan (Dedicated Enterprise).

Deliverability and risk-tolerance reporting for your numbers. **Scope** — Reports are organization-scoped: any API key in the organization returns the whole organization's scorable fleet, regardless of which numbers a particular key is attached to. **Eligibility** — Risk scoring is available for dedicated numbers (Dedicated Commercial or Dedicated Enterprise) and inbound numbers (Inbound Basic); shared and trial numbers return `403 dedicated_plan_required`. Those are the only lines whose per-number usage is meaningful to score. **What the score means** — Each number gets a `risk_score` from 0 (lowest risk) to 100 (highest), mapped to a `risk_level`: `low` (0-29, healthy), `medium` (30-59, monitor), `high` (60-100, likely to be filtered/suspended by carriers). The score is the clamped sum of ten additive risk factors (see `RiskFactors`); positive factor scores raise risk, negative scores (bonuses) lower it. High **inbound** volume and engagement lower risk; high **outbound** volume, bursts, low reply rates, and templated content raise it. Risk is attributed to what a number does rather than to the traffic it receives, so `newConversationBursts` counts only the conversations the number itself opened — on every line type, a rush of customers texting in is never read as a blast. **Inbound lines are scored differently** — Inbound numbers are reply-only, so the factors that assume cold outreach are re-scoped for them: `outboundConversations` and `inboundPercentage` report `status: "not_applicable"` with a score of 0 (they are structurally fixed on a reply-only line), `inboundConversations` earns no volume bonus, and `inboundMsgCount` uses a relaxed threshold worth fewer points. The remaining factors — reply rate, total contacts, message balance, message bursts, and message similarity — are scored identically to dedicated lines. Each report entry carries a `line_type` so you can tell which profile was applied. **How it's computed** — Fully real-time: every request recomputes from Postgres over the requested window (there is no cache on the report endpoints). The metric fan-out is collapsed into a handful of org-wide `GROUP BY allocation_id` queries that run on a single database connection, so cost is roughly independent of fleet size. Conversation-initiation signals read the `channel_thread_stats` rollup (one row per conversation, holding its earliest message + direction); engagement, contacts, and bursts scan the windowed `messages`; message similarity derives a SimHash per outbound message at read time. **Window** — Defaults to the trailing 30 days; override with `days` or an explicit `from`/`to` epoch-ms range (see the per-endpoint query params).

Authenticated account, sender numbers, and contact cards.

Find My friend locations (device passthrough).

Sending surfaces (iMessage/Blooio, Twilio, WhatsApp, RCS, Apple Messages for Business) and their capabilities.

Channel routing / number pools: ordered sets of channels walked by priority for the agnostic send.

Contacts, their channel identities, capabilities, timeline, and tags.

Conversations and chat-level actions (typing, read, contact card, background).

Send messages and read message history, status, events, and reactions.

Native iMessage polls (Blooio channels).

Group chats on group-capable channels (Blooio, WhatsApp).

Webhook subscriptions and delivery attempts for inbound + lifecycle events.

Unified activity feed across messages, polls, groups, reactions, typing, payments, and messaging-safety state changes.

Phone number lookup and geocoding (enterprise plans).

Every number the organization rents from Blooio, as one resource keyed by the number itself. A number carries one or more `products`: `imessage` (a Blooio iMessage line), `sms` (Blooio SMS), and `voice` (Blooio Voice). Each product is a channel, listed in the number's `channels`, and that channel is what you send and call from. Search and buy Blooio SMS and Blooio Voice numbers here; iMessage lines are bought through `/channels/blooio/purchases`. Blooio SMS and Blooio Voice must be enabled on the organization, and an organization holds up to 5 of these numbers unless Blooio raises its limit. OAuth apps need `numbers:read` to read and `numbers:manage` to buy, change, and release.

US carrier registration for Blooio SMS. Carriers deliver texts from a local number only once the number sits on a 10DLC campaign they've provisioned. The organization registers one brand (who is sending), then one or more campaigns (what it sends and how people opt in). Blooio assigns the organization's SMS numbers to its oldest provisioned campaign automatically; `PATCH /numbers/{number}` with `campaign_id` moves a number to another. Registration status changes arrive as `registration.brand.updated` and `registration.campaign.updated` webhooks. OAuth apps need `numbers:read` to read and `numbers:manage` to register.

Calls on the organization's Blooio Voice numbers. Every call has a handler that takes its audio once it's answered: `stream` (your WebSocket server, speaking the Blooio media stream protocol), `agent` (the Blooio agent that owns the number), or `softphone` (a teammate in the dashboard). Inbound calls go to the handler set in the number's voice settings (`PATCH /channels/{channel}/settings` with `inbound`); with `api`, the call rings until you answer it with `POST /calls/{call_id}/answer`. A call lasts at most 4 hours. Call status changes arrive as `call.ringing`, `call.answered`, and `call.ended` webhooks. OAuth apps need `calls:read` to read and `calls:write` to place and control calls.

Programmatic API key management — create keys, list them, deprecate them, and assign them to channels. **Blooio Apps (OAuth) only.** Every endpoint under this tag is callable *only* with a Blooio Apps OAuth access token (`blo_at_...`) whose install was granted the `apikeys:read` / `apikeys:manage` scopes. API-key and dashboard authentication are rejected with `403 oauth_token_required`. This mirrors the API-key management that has always lived in the dashboard, exposed to installed apps under explicit user consent.

Model-backed decisions about conversations. Bloobability v2 returns, for each policy you write, a calibrated probability that it holds and a separate estimate of whether the conversation can answer it, from the instant or full tier you choose. The deprecated v1 gauge stays documented for reference.