Migrate from BlueBubbles

This guide moves an existing BlueBubbles integration to Blooio and onto Apple Messages for Business, Apple's official channel for businesses. Your business logic stays the same. What changes is the transport: the endpoints, the auth header, and the webhook fields, all mapped below.

The three steps

1. Get a free sandbox and build. Connect a free Apple Messages for Business sandbox, point your code at the Blooio API, and build your bot with every feature unlocked: quick replies, list pickers, forms, Apple Pay, and live agent handoff.
2. Submit to Apple's Experience Review. Apple tests the whole conversation before you go live. Blooio records the walkthrough and submits it for you, and the AI bot on the Growth plan already checks every box Apple looks for.
3. Go live. Once Apple approves, turn on the Message button in Maps, Search, your site, and your app. Customers who can't be reached on Apple Messages for Business fall back to RCS Business Messaging, then SMS.

Endpoint and field mapping

• BlueBubbles' Private API features need System Integrity Protection turned off on the Mac. Blooio needs no Mac, no tunnel, and no SIP changes.
• BlueBubbles has no SMS fallback of its own. On Blooio, customers who can't be reached on Apple Messages for Business fall back to RCS Business Messaging, then SMS.

BlueBubbles's own reference: https://docs.bluebubbles.app/server/developer-guides/rest-api-and-webhooks.

Before and after

BlueBubbles:

curl -X POST "https://your-mac.example.com/api/v1/message/text?password=$BB_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "chatGuid": "any;-;+15551234567",
    "tempGuid": "temp-8f3a2c",
    "message": "Thanks for reaching out. How can we help?"
  }'

Blooio:

curl -X POST https://api.blooio.com/v4/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $BLOOIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "Thanks for reaching out. How can we help?"
  }'

Receive messages

Every inbound message arrives as a message.received webhook. On Apple Messages for Business the sender is an opaque id Apple mints for that customer and your brand, not a phone number. Reply to data.chat_id and the thread stays intact.

{
  "id": "evt_018f7b2a-1c3d-7e4f-9a2b-0c1d2e3f4a5b",
  "type": "message.received",
  "data": {
    "message_id": "msg_018f7b2a-8e5b-7f00-a1b2-0f1a2b3c4d5e",
    "chat_id": "chat_018f7b2a-77aa-7c22-9d3e-4f5a6b7c8d9e",
    "channel_type": "amb",
    "direction": "inbound",
    "sender": "opaque-amb-customer-id",
    "text": "Where's my order?",
    "attachments": []
  }
}

Teach your bot the Apple Messages for Business payloads

Apple reviews the whole conversation before you go live, so the bot has to behave the way Apple expects, not just deliver text. The first reply should disclose that it is automated and triage with a Quick Reply of your top four reasons plus "Something else":

curl -X POST https://api.blooio.com/v4/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $BLOOIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "interactive": {
      "kind": "quick_reply",
      "summary_text": "Hi, I'm Blue, Acme's automated assistant. What can I help with?",
      "items": [
        { "id": "order", "title": "Track an order" },
        { "id": "return", "title": "Start a return" },
        { "id": "billing", "title": "Billing" },
        { "id": "store", "title": "Store hours" },
        { "id": "other", "title": "Something else" }
      ]
    }
  }'

Every rule Apple checks, from the 5-second welcome to live agent handoff and keywords, is in Pass the Experience Review. The payload shapes are in Interactive messages.

Smart fallbacks to RCS Business Messaging and SMS

Not every customer is on an Apple device, and Apple Messages for Business conversations always start with the customer. Put your channels in a priority: Apple Messages for Business first, RCS Business Messaging second, SMS third. Send without from and Blooio picks the right channel for each customer, so the same code reaches iPhone, Android, and everything else.

Outbound

Apple Messages for Business is customer-initiated. The only business-first message is an Apple-approved business invitation to a customer who opted in. Move cold outbound campaigns to RCS Business Messaging or SMS through the same API.

Related

• Apple Messages for Business overview
• Launch Apple Messages for Business
• Pass the Experience Review
• Interactive messages
• Priorities