Business invitations (AMB)

Start an Apple Messages for Business conversation with a customer by sending an Apple-managed invitation template to their phone number.

Most Apple Messages for Business (AMB) conversations are customer-initiated — the customer taps a Messages button and you reply. Invitations are the one sanctioned way to start a conversation business-first: you send an Apple-managed notification template to a customer's phone number, and if they accept, a normal two-way AMB conversation opens.

Note Invitations require explicit setup and consent (below). They are not marketing blasts — unsolicited invitations are prohibited by Apple and will get your business flagged.

Requirements

Apple approval. Your business must be approved for the Invitations feature by Apple. Access is granted per business.
Apple-managed templates only. You cannot author your own template; you reference an Apple template id authorized for your business (e.g. binaryChoice.engage.withImage). See How to get a template id.
Explicit opt-in. The customer must have opted in to messaging at your point of sale (website signup, IVR, etc.) and given you the phone number. Opt-outs must be honored.
iOS 18 / macOS 15+ on the customer's Apple devices.

Send an invitation

Invitations use the same POST /v4/messages endpoint as every other send, with a top-level invitation content field. Because there is no AMB conversation yet, you address the customer by phone number (not an opaque AMB id):

curl -X POST https://api.blooio.com/v4/messages \
  -H "Authorization: Bearer bl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "your-amb-alias",
    "to": "+15551234567",
    "invitation": {
      "template_id": "binaryChoice.engage.withImage",
      "reference_id": "case-1009273616",
      "parameters": { "brandName": "Your Brand", "brandLogo": "<base64-png>" },
      "locale": "en-us"
    }
  }'

Try it

Fields

Field	Type	What it is
`from`	string	Your AMB sender alias. (Or POST to `/v4/channels/{alias}/messages` and omit `from`.)
`to`	string	The customer's phone number in E.164. Blooio addresses Apple as `tel:+E164` for you.
`invitation.template_id`	string	Required. The Apple-managed template id authorized for your business.
`invitation.reference_id`	string	Required. Your business context id (order/case number). Echoed back on the CloseSession webhook if the customer leaves. Max 1000 chars; no quotation marks or apostrophes.
`invitation.parameters`	object	Template parameters. Varies per template — `binaryChoice.engage.withImage` takes `brandName` and `brandLogo` (a base64 PNG).
`invitation.locale`	string	BCP-47 locale. Defaults to `en-us`.

How to get a template id

You don't create invitation templates — Apple does. Request the Invitations feature for your business through Apple, and Apple authorizes a set of template ids for specific use cases. Reference one of those ids in template_id; sending an unauthorized template is rejected. The standard "Connect Using Messages" template is binaryChoice.engage.withImage. The current, authoritative list is what Apple authorizes for your Business id.

What happens next

An invitation creates (or reuses) an AMB chat and sends immediately. The customer sees a branded invitation bubble with Yes / No:

Accept (Yes) — Apple mints the customer's opaque AMB id and the chat becomes a normal two-way AMB conversation. From then on, address the customer by that opaque id (delivered on the inbound message.received webhook), not their phone number.
Decline (No) — no opaque id is created; the customer is not reachable via AMB.
Leave / Report Junk — the customer can opt out at any time. Blooio surfaces this as a chat close (Apple's CloseSession), carrying your reference_id. You must not invite that number again until they re-opt-in.

Until the customer accepts, you can only send further invitation templates — free-form messages to a not-yet-accepted invitee are rejected.