Apple Messages for Business

Connect your brand to Apple Messages for Business and answer customers inside the Messages app through the Blooio v4 API — inbound-first, brand-scoped, and consent-gated.

Apple Messages for Business lets customers start a conversation with your brand from across Apple's ecosystem — and lets you answer them through the same Blooio v4 API you already use for iMessage, SMS, RCS, and WhatsApp. It is inbound-first, brand-scoped, and consent-gated: a customer always taps first, every message is tied to your verified business, and you only message people who have engaged (or explicitly opted in).

This page is the map. It covers what Apple Messages for Business is, how a conversation begins, how to connect a channel to Blooio, how to send your first reply, and where to go for each feature.

Why Apple Messages for Business

  • Native, branded, and verified. Your logo, name, and brand color sit at the top of the thread with a verified checkmark. Customers know they're talking to the real you, inside the Messages app they already have.
  • Rich by default. Beyond text and media you can send list pickers, time pickers, dynamic forms, and quick replies, take payment with Apple Pay, and let customers sign in — all without leaving the conversation.
  • One API. Apple Messages for Business is a channel on Blooio's v4 API (channel_type: "amb"). The same POST /v4/messages, chats, webhooks, idempotency, and error model you use elsewhere apply here.

Base URL: https://api.blooio.com/v4 (staging https://api-staging.blooio.com/v4). Authenticate every request with your API key as a bearer token: Authorization: Bearer bl_live_....

How a conversation starts

Apple Messages for Business is customer-initiated. A customer reaches you from a Messages entry point you place on your surfaces:

Entry point Where it appears
Messages button Your website and app
Message Suggest Next to your phone number when a customer taps it on iPhone
Apple Maps Your business's place card in Maps
Spotlight & Siri Search results for your brand
Links and QR codes Emails, texts, social posts, print, packaging, and signage

Tapping any of them opens a thread addressed to your business. Every one is a link to your Business ID, such as https://bcrw.apple.com/urn:biz:<business-id>, and can carry an intent, a group, and pre-filled text. Blooio passes the intent and group to you as routing on the first message. See Entry points for every link form, the website button, and examples, and the branding guide for naming and button rules. The one sanctioned way to start a conversation business-first is a business invitation — an Apple-managed template you send to a phone number that has opted in.

The end-to-end lifecycle: a customer taps an entry point, you receive the inbound over a webhook, and you reply over the same API. Click a step for details.

The opaque recipient id

When a customer first messages you, Apple mints an opaque id for that customer, scoped to your business. It looks like urn:mbid:AQAAY0vH…. It is not a phone number or an email, and you can't derive it — Blooio hands it to you as the sender on the inbound message.received webhook that opens the conversation. Address every reply to that id (to); it stays stable for that customer and your brand, so the conversation always threads correctly.

Note Because Apple Messages for Business is inbound-first, you always have the opaque id before you need to reply. You never cold-message an id you haven't been given — the only exception is an invitation, which is addressed to a phone number.

Connect a channel to Blooio

  1. Register with Apple. Create a Messages for Business account in Apple Business Register and complete Apple's brand verification. Apple issues your Business ID.
  2. Choose Blooio as your Messaging Service Provider. Select Blooio as your MSP during registration so Apple links your Business ID to Blooio.
  3. Connect in the dashboard. Open Business Channels → Apple Messages and link your Business ID.
  4. Assign an alias. Give the channel a short alias such as support. You'll use it as from on sends (or in the channel-scoped URL). The alias survives swapping the underlying integration, so prefer it over the raw ch_... id in your code.

Once linked, the channel appears on your Channels priority list alongside your numbers, and GET /v4/channels lists it with channel_type: "amb".

Send your first reply

A customer messages you; Blooio delivers a message.received webhook carrying the opaque id. Reply by addressing that id from your Apple Messages for Business alias:

curl -X POST https://api.blooio.com/v4/messages \
  -H "Authorization: Bearer bl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9d2e-7a9b-4c1e-9f2a-8b6d5e4c3a21" \
  -d '{
    "from": "support",
    "to": "opaque-amb-customer-id",
    "text": "Thanks for reaching out — how can we help?"
  }'
Try it
  • from — your Apple Messages for Business alias. Omit it and POST to /v4/channels/support/messages instead, where the alias lives in the path.
  • to — the opaque id from the inbound webhook.
  • Idempotency-Key — makes a blind retry safe; see Idempotency.

Already holding the chat? Reply with POST /v4/chats/{chatId}/messages and drop from/to — the chat fixes both the sender and the recipient.

A successful call returns a queued message (id, chat_id, channel_id, status). Track delivery with GET /v4/chats/{chatId}/messages/{messageId}/events or a webhook.

What you can send

Content Field Guide
Plain text text Rich links & media
Images, video, files (≤ 100 MB) attachments Rich links & media
Rich link card rich_link Rich links & media
Quick reply, list/time picker, form, custom app interactive Interactive messages
Apple Pay request interactive (kind: apple_pay) Apple Pay
Sign in (OAuth 2.0) interactive (kind: authenticate) Sign in
Business invitation invitation Business invitations
Typing indicator POST /v4/chats/{chatId}/typing Conversation lifecycle

When a customer shares a location

A location the customer shares arrives as a message.received of type location. Its location holds the coordinates, and the place's name and address when Apple has them; text holds the address, the name, or "latitude, longitude". Apple expects your reply to name the place back so the customer can correct it.

"location": {
  "latitude": 37.3349,
  "longitude": -122.009,
  "name": "Apple Park",
  "address": "1 Apple Park Way, Cupertino, CA 95014"
}

Reactions (tapbacks)

Apple doesn't tell a Messaging Service Provider which message a customer reacted to. This is the biggest difference from iMessage on a Blooio number, where the device reports a tapback together with the id of the message it landed on and the bubble within it, so message.reaction names the exact message and, on a carousel, the exact image (part_index and reacted_attachment).

On Apple Messages for Business, every reaction reaches Blooio as an ordinary inbound text message. Its body is the line the customer's own device displays, written in the customer's language. It has no message id, no bubble index, and no reaction code. This is the complete payload Apple sends for a tapback:

{
  "v": 1,
  "id": "1d212f5a-d69d-4051-acb6-1813c0c39fd7",
  "type": "text",
  "body": "Questioned “Your table is booked for 7pm”",
  "sourceId": "urn:mbid:AQAAYz0C6r9JC2l0EmI…",
  "destinationId": "39b363a9-0d57-45b1-96e5-3481756d7a21"
}

id is the id of the reaction itself, not of the message it reacts to. The only link back to your message is the text Apple quotes, and Apple only quotes text:

The customer reacts to Apple's text (English)
A text bubble, with a tapback Loved “See you at 3”
A text bubble, with an emoji Reacted 🎉 to “See you at 3”
An image Loved an image or Reacted 🎉 to an image
An interactive message (quick reply, list or time picker, form) Liked 1 Business Message
Any bubble, with a sticker Reacted with a sticker to "See you at 3", plus the sticker image as an attachment

How Blooio relays them

Blooio passes on what Apple sends and only fills in a message id when Apple's text identifies one:

  • A tapback or emoji on a text bubble arrives as message.reaction. Blooio finds the message among the chat's 25 most recent whose text matches Apple's quote, and keys the event to it (message_id, original_text). There's no message.received for it. Apple shortens a long quote with …, so a quote matches a message that starts with it. When two recent messages have the same text, the reaction goes to the newer one. When no message matches, Apple's line arrives as message.received instead.
  • Everything else arrives as message.received, with Apple's line as text. That covers reactions to images and interactive messages, stickers (the sticker image is in attachments), and wording Blooio doesn't recognize. Blooio doesn't guess a message for these: if you sent ten images, Loved an image doesn't say which one the customer liked, and neither can Blooio.
  • Removing a reaction sends nothing. Apple doesn't tell the provider when a customer takes a tapback back, so don't wait for action: "remove" on this channel.

Blooio recognizes Apple's wording in English, Spanish, French, German, and Portuguese. In any other language, a reaction to a text bubble also arrives as message.received.

Note Treat a reaction on this channel as a signal about the conversation, not as a pointer to a specific message. If you need to know which of several items a customer wants, ask with a list picker or quick reply: the reply carries the id of the option they picked.

Test your bot before Apple's review

If your own bot answers your Apple Messages channel, the Evaluate tab in Agents → Builder grades it against Apple's Messages for Business Experience Review. Pick Your bot on … and run the test conversations: Blooio plays scripted customers who say hello, ask for a person, send gibberish, write in Spanish, share a location and offer a card number, then grades how your bot answers. Your bot is listed once it has an active webhook you created that receives message.received for the channel. If you don't see the Evaluate tab, ask support to turn it on.

What your bot receives. Each test conversation opens its own sandbox chat on your channel, with a customer of its own. The webhook you picked gets a signed message.received like any other, with two more fields in data:

Field Value
data.sandbox true
data.evaluation_run_id The run's id, the same on every event of one run

The sender is a test id such as urn:blooio:eval:… rather than an Apple opaque id. Only the webhook you picked gets the run's events, and each delivery is tried once. A failed one is reported as your bot not replying, and it isn't counted among the webhook's failed deliveries.

Reply as you normally would. Answer through the same calls: POST /v4/chats/{chatId}/messages, POST /v4/messages addressed to the sender, and POST /v4/chats/{chatId}/typing. Requests are validated as usual, so a malformed send still returns a 4xx. Blooio records your messages and typing instead of passing them to Apple, and sends their message.sent events to the same webhook if it subscribes to them. Your typing is graded too: about a second of it before each message, and none left on after your last. Blooio waits about 30 seconds for your first reply to each message and a few quiet seconds after your last, so a bot that answers in several messages is graded on all of them. A run takes at most four minutes, with up to three conversations at once.

Skip real side effects. Check data.sandbox before anything that changes the world outside the conversation, such as placing an order, booking an appointment, charging a card, paging a person or writing to your CRM, and reply as if you had:

const isEvaluation = event.data.sandbox === true;
if (!isEvaluation) await placeOrder(order);

A test customer who asks for a person is graded on what your bot tells them, so say in the reply that a person will pick up.

Nothing reaches Apple. A sandbox chat has no Apple conversation behind it. Nothing is delivered to a device, and no test customer becomes a monthly active user, so a run isn't billed. Its messages stay out of your conversation list and message stats. While a run plays, its chats and their "Blooio evaluation" contacts can appear in GET /v4/chats and GET /v4/contacts; when the run ends, they are closed and their messages deleted.

Where to go next

Guide What it covers
Entry points Links, the website button, QR codes, Maps, Message Suggest, and routing
Branding Naming rules, approved buttons, and website placement
Interactive messages Quick replies, list/time pickers, dynamic forms, custom iMessage apps
Rich links & media Rich link cards, images, video, and files
Sign in (OAuth 2.0) Authenticate customers with your identity provider in-thread
Business invitations Start a conversation business-first with an Apple template
Apple Pay Take payment inside the conversation
Conversation lifecycle Typing indicators, read receipts, handoff, and closing
Monthly active users What counts as a Monthly Active User
Capabilities & limits OS floors, device gating, timeouts, and TTLs