Blooio SMS

Blooio SMS gives your organization local US numbers that send and receive SMS and MMS. A number is bought with the sms product, registered with US carriers through 10DLC, and then used as a from on POST /v4/messages like any other sender.

Note Blooio SMS and Blooio Voice are enabled per organization. Until they're enabled on yours, buying, searching, and changing numbers and every 10DLC endpoint return 403 feature_not_enabled. An organization holds up to 5 of these numbers unless Blooio raises its limit.

Numbers

Every number your organization rents from Blooio is one resource under /v4/numbers, keyed by the number itself and described by its products:

Each product is a channel, listed in the number's channels with its own channel_id and status. One number can carry sms and voice together.

Search and buy

Search inventory by area code, state, or digits, then buy the numbers you picked. Purchases are asynchronous and need an Idempotency-Key; replaying the same key returns the original purchase.

curl 'https://api.blooio.com/v4/numbers/available?products=sms,voice&area_code=415' \
  -H 'Authorization: Bearer bl_live_...'

curl -X POST 'https://api.blooio.com/v4/numbers' \
  -H 'Authorization: Bearer bl_live_...' \
  -H 'Idempotency-Key: sms-order-001' \
  -H 'Content-Type: application/json' \
  -d '{ "phone_numbers": ["+14155550123"], "products": ["sms", "voice"] }'

The response is 202 with a purchase (pur_...). Poll GET /v4/numbers/purchases/{purchase_id} until its status is completed or failed, or subscribe to number.purchase.completed and number.purchase.failed.

Change and release

PATCH /v4/numbers/{number} takes products (the full set the number should carry; a product you leave out is turned off and its channel retired) and campaign_id (move the number's SMS channel to another 10DLC campaign). DELETE /v4/numbers/{number} releases the number.

GET /v4/numbers lists every number the organization holds, iMessage lines included; filter with products=sms.

10DLC registration

US carriers deliver texts from a local number only once the number sits on a 10DLC campaign they've provisioned. Until then the number's SMS channel is pending_verification and sends are refused.

1. Register a brand: who is sending. PUT /v4/10dlc/brand with an entity_type and the brand's details. GET /v4/10dlc/options lists the entity types, verticals, and use cases.
2. Verify a sole proprietor: a SOLE_PROPRIETOR brand is verified by a PIN texted to its mobile_phone. POST /v4/10dlc/brand/otp sends it and PUT /v4/10dlc/brand/otp submits it.
3. Create a campaign: what you send and how people opt in. Check a use case first with GET /v4/10dlc/usecases/{usecase}/qualification, then POST /v4/10dlc/campaigns with sample messages, the opt-in flow, and the HELP and STOP replies.
4. Wait for carriers: the campaign moves through the registry's review (tcr_*), the carriers' vetting (review_*), and the carriers themselves (mno_*). Once it's mno_provisioned, Blooio assigns the organization's waiting SMS numbers to it, and each becomes active once carriers accept it.

Blooio assigns new SMS numbers to the organization's oldest provisioned campaign automatically. A review_failed or mno_rejected campaign carries failure_reasons; fix its samples with PATCH /v4/10dlc/campaigns/{campaign_id} and appeal it.

Status changes arrive as webhooks:

The dashboard's 10DLC tab walks through the same steps.

Sending

Send from an SMS number with the number (E.164) or its SMS channel id as from:

curl -X POST 'https://api.blooio.com/v4/messages' \
  -H 'Authorization: Bearer bl_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "+14155550123",
    "to": "+12125550199",
    "text": "Your table is ready."
  }'

Text and media (MMS) are supported, one recipient at a time. Delivery status arrives on the usual message webhooks. A send is refused with:

• 409 channel_not_active: the number isn't on a provisioned campaign yet.
• 409 recipient_opted_out: the recipient replied STOP.
• 409 group_unsupported_for_channel_type: SMS has no group chats.

Receiving and opt-out

Inbound texts and MMS arrive as message.received on the number's SMS channel. Carriers handle the STOP and START keywords themselves: a STOP opts the sender out on every SMS number in your organization, and a START opts them back in. Blooio records both, so sends to an opted-out recipient are refused before they reach a carrier. HELP and STOP are answered with your oldest approved campaign's help_message and optout_message.

Blooio tells you about each one with contact.opted_out or contact.opted_in on the number the keyword came in on, and with a note in the conversation. Only SMS is affected: a routed send can still reach the contact on another channel.

Scopes

API keys have full access. OAuth apps need numbers:read to read numbers and registrations, numbers:manage to buy, change, release, and register, and messages:write to send.

Related

• Blooio Voice
• Message sending
• Idempotency
• Webhooks