Apple Messages for Business developer guide: API, list pickers, integrations

Apple Messages for Business looks like "the iMessage API" from the outside. Most teams discover it isn't once they start building. The customer has to start the conversation. You don't get the customer's phone number. You usually can't call Apple's API directly unless Apple has approved you as a messaging service provider. The rich parts, like list pickers, time pickers and Apple Pay, are excellent, but they only work inside a conversation the customer opened from Maps, Safari, Siri or a button on your site.

This guide covers how the API is structured, what each rich component is for, how CRM and contact-center integrations fit, and when an MSP or a different product is the easier path. We make Ready, and Ready is not an Apple Messages for Business provider. We sell a different product, a blue line, and we'll explain where it fits and where it doesn't.

What Apple Messages for Business actually is

Apple Messages for Business (AMB) is a customer-service channel inside the Messages app. A customer taps a "Message" button on your Apple Maps listing, your website or a search result. That opens a thread in Messages with your verified brand name and logo, and your agents or bots answer.

Three properties shape everything you build:

1. The customer texts first. You can't start an outbound conversation to a list. AMB is an inbound support and commerce channel, not a marketing or notification channel.
2. Identity is opaque. Your system receives an Apple-issued identifier for the customer, not a phone number or email. If you want to tie the thread to a CRM record, the customer has to tell you who they are, usually through an authentication flow.
3. Apple controls access. Your business registers through Apple's business registration process and goes through review. Messages flow through a messaging service provider (MSP) that Apple has approved, or through your own platform if Apple approves you as one.

That third point is what decides most build-versus-buy conversations.

How access and the REST API work

Registration and the MSP layer

Before a single message moves, the business needs an approved Messages for Business account: brand assets, the support hours you commit to, the entry points you'll use, and an MSP attached to the account. Apple reviews it. Plan for that review in your project timeline, because you can't skip it with code.

The MSP is the system that holds the connection to Apple's Messages for Business servers. Your options:

• Use an existing MSP or contact-center suite that already has Apple approval. You integrate with their API or UI, not Apple's.
• Become an MSP yourself. This makes sense if you're a platform that wants to offer AMB to many businesses. You apply to Apple, build to its REST spec, and pass its review.

The shape of the API

If you go the MSP route, the integration looks like most webhook-based messaging APIs, with Apple-specific details:

• Inbound: Apple's servers send HTTPS POST requests to your MSP endpoint for each customer message, typing indicator or conversation-closed event. Each one carries identifiers for the business and the opaque customer ID.
• Outbound: you POST messages back to Apple with those identifiers. Text is straightforward. Interactive messages carry a structured payload that describes the component.
• Attachments: these are encrypted and uploaded and downloaded separately from the message body, so budget time for that handling.
• Session behavior: you track open and closed conversations and route them to agents or automation.

Apple's own Messages for Business documentation is the source of truth for header names, payload schemas and attachment encryption. Those details change, and we won't reproduce them here from memory. If you've built inbound SMS webhooks before, the routing and idempotency patterns carry over directly. Our post on receiving SMS via API with inbound webhooks covers the same plumbing: verify the sender, deduplicate, and acknowledge fast, then process.

Rich components: what each one is for

The rich components are why teams want AMB. Each is an interactive message that renders natively in Messages and returns a structured reply to your system.

Some practical notes from the spec's design:

• Every interactive message has two appearances: the bubble shown when you send it and the bubble shown after the customer replies. Design both, or the thread looks broken in history.
• List pickers are the workhorse. If you build one component first, build this one. It replaces "reply 1, 2 or 3" menus, which customers mistype.
• Apple Pay needs a payment processor and merchant setup on top of AMB. It's a separate workstream, so don't treat it as a checkbox.
• Authentication solves the identity problem. Without it, your CRM sees an anonymous ID. With it, you can match the thread to a customer record and show the agent order history.

Integrations with CRMs and CCaaS

Most businesses never touch Apple's API at all. They switch AMB on as a channel inside a contact-center or CRM suite that is already an approved MSP or partners with one. Salesforce, Zendesk, Genesys and LivePerson have all offered it in some form. Check each vendor's current support and which components they render, because coverage of list pickers, Apple Pay and custom extensions varies.

What to check in any integration:

• Which rich components render in the agent console, not just in the customer's Messages app.
• How identity mapping works. Does it use the authentication component to attach the thread to a contact, or does every chat start anonymous?
• Routing and SLAs. Apple expects you to staff the hours you committed to, so queue and after-hours behavior matters.
• Reporting and transcript export into your CRM or data warehouse.

If your main channel is SMS and you're mapping texts to CRM records by phone number, AMB will feel different. There is no number to match on. Our guide to SMS integrations for CRMs covers the phone-keyed model for comparison.

When an MSP abstraction is easier

Becoming an MSP is real work: Apple's approval, the encrypted attachment pipeline, interactive payload builders, an agent experience, uptime, and ongoing spec changes. That effort is worth it if you're a CCaaS or vertical platform and AMB is a feature you'll sell to hundreds of businesses.

For nearly everyone else, an existing MSP or CCaaS is easier:

• You're one business, not a platform. Use your contact-center vendor's AMB channel.
• You need it this quarter. Apple's review of a new MSP plus your build time rarely fits a quarter.
• Your agents already live in one console. Adding AMB there beats building a new inbox.

Build your own MSP when AMB is core to your product, you need components your vendor doesn't render, or you need control over data residency and routing that a vendor won't give you.

Where a blue line fits (and how it differs)

Many teams come to AMB because they want blue bubbles, and then find out it can't text first. That's the gap our blue line fills. It is a different product, and the difference matters.

A Ready blue line sends texts as iMessage, so they show up blue on iPhones with the business's name and photo. The business can text first. It needs no 10DLC registration, so you can start as soon as the line is set up. What it doesn't have is AMB's rich components. There are no list pickers, time pickers or Apple Pay sheets, and no Maps or Siri entry points.

The limits are deliberate:

• Unlimited texting with people the business already talks to
• Up to 50 new conversations a day per line
• Up to 2 texts to someone until they reply, and photos only after they reply
• Texts to Android phones go from the account's regular number. If the account already had a number they bill at the regular text price; if the blue line came with its green number, they bill at 6 cents a segment once the account registers

Pricing is $99 a month per line plus 6 cents a segment for each text sent. A reply to a blue line is also 6 cents a segment, and reactions are free.

Worked example (assumptions stated): one blue line sends 1,200 single-segment texts to iPhone users in a month and receives 900 single-segment replies.

• Line: $99
• Segments: (1,200 + 900) × $0.06 = 2,100 × $0.06 = $126
• Blue line total: $99 + 2,100 × $0.06

Say the same account also texts Android contacts, sending 500 texts and receiving 300 replies, all single-segment SMS. Those 800 segments bill at the Standard rate of $0.0075 per segment plus a $0.0045 carrier fee per segment. That figure excludes the optional $0.003-per-segment scrub and landline validation surcharges, which are off by default.

Replies, reactions and typing indicators land in the same inbox thread as SMS. Campaigns and drip campaigns send from regular numbers, not the blue line. The developer docs are at docs.tryready.com/guides/imessage and docs.tryready.com/api/imessage. Our posts on the iMessage API for business and on one thread for blue and green texts go deeper.

For the SMS side, a send is one request:

POST https://api.tryready.com/v1/messages
X-API-Key: <key>
Idempotency-Key: 6f1c2a9e-0b7d-4c55-9a3e-2d8f41b7c901
Content-Type: application/json

{"to": "+12125550199", "body": "Your appointment is confirmed for Tuesday at 10 AM.", "consent_attested": true}

consent_attested is your promise that the recipient agreed to texts. The send records an attestation (who sent, to how many, when), but it is not a per-contact consent record. Your app keeps that.

A quick decision checklist

• The customer starts the chat, and you want pickers, payments or sign-in in the thread: Apple Messages for Business, through your CCaaS or an MSP.
• You're a platform selling AMB to many businesses and need full control: apply to become an MSP.
• You need to text first, in blue, without 10DLC registration: a blue line.
• You need campaigns, reminders and reach to every phone: registered SMS. That's the cheapest per message and works on Android.

Plenty of businesses end up running two of these: AMB for inbound support from Maps and the website, and SMS or a blue line for outbound reminders and follow-ups.

The takeaway

Apple Messages for Business is a strong inbound channel with the best interactive components in messaging. It's gated by Apple's review, it's customer-initiated, and it's usually easiest to adopt through a contact-center vendor rather than by building an MSP. If what you need is outbound blue texts or texting that reaches every phone, that's a different problem.

If that's your case, you can create a Ready account and try SMS with the first 20 texts free (one-to-one sends; a card on file is required). Add a blue line once you know your outbound volume.