Find My & Check In bubbles

Apple ships several first-party iMessage apps — Find My (location sharing) and Check In (safety) among them. Each renders as a custom bubble like any other iMessage app, so you send them with the same imessage_app content type: point at Apple's bundle id (team id 0000000000) and provide the app's url payload.

Note

Apple system apps are Blooio iMessage only. The bubble's card renders from app_name / caption on every device, but the live experience (a running Check In timer, an active location share) only activates when url is a valid payload from an authentic Apple session — Apple end-to-end encrypts the session data inside it. Blooio transports the bubble exactly as you provide it and never inspects or alters the payload.

Apple app identifiers

Warning

Apple Cash money movement is gated by the device Secure Element and cannot be initiated through the API — you can receive and display an Apple Cash bubble, but not create a payment request from it.

Find My

Find My bubbles come in two flavors, shown by the label on the card:

• Requested Location — ask a contact to share their location.
• Started Sharing Location — share your own location.

The url is a query string carrying Apple's compressed location-session data:

?FindMyMessagePayloadVersionKey=v0&FindMyMessagePayloadZippedDataKey=<payload>

cURL

curl -X POST 'https://api.blooio.com/v4/channels/CHANNEL_ID/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "imessage_app": {
      "bundle_id": "com.apple.findmy.FindMyMessagesApp",
      "team_id": "0000000000",
      "url": "?FindMyMessagePayloadVersionKey=v0&FindMyMessagePayloadZippedDataKey=<payload>",
      "app_name": "Find My",
      "caption": "Requested Location"
    }
  }'

Node.js

await fetch('https://api.blooio.com/v4/channels/CHANNEL_ID/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+15551234567',
    imessage_app: {
      bundle_id: 'com.apple.findmy.FindMyMessagesApp',
      team_id: '0000000000',
      url: '?FindMyMessagePayloadVersionKey=v0&FindMyMessagePayloadZippedDataKey=<payload>',
      app_name: 'Find My',
      caption: 'Requested Location', // or "Started Sharing Location"
    },
  }),
})

Check In

Check In lets someone notify a contact they've arrived safely, with a timer. The url is a query string; the key parameters are:

?messageType=1&interfaceVersion=1&sessionID=<uuid>&receiverHandle=+15551234567&sessionType=2&estimatedEndTime=<unix>&shareURL=https://www.icloud.com/share/<id>&sharingInvitationData=<payload>

curl -X POST 'https://api.blooio.com/v4/channels/CHANNEL_ID/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "imessage_app": {
      "bundle_id": "com.apple.SafetyMonitorApp.SafetyMonitorMessages",
      "team_id": "0000000000",
      "url": "?messageType=1&interfaceVersion=1&sessionID=<uuid>&receiverHandle=+15551234567&sessionType=2&estimatedEndTime=<unix>&shareURL=https://www.icloud.com/share/<id>&sharingInvitationData=<payload>",
      "app_name": "Check In",
      "caption": "Check In: Home"
    }
  }'

Receiving

When a contact sends one of these, you get a message.received webhook with message_type: "imessage_app" and the imessage_app object — app_name (Find My / Check In), caption / summary (e.g. Requested Location, Check In: Home), and the raw url payload. Branch on bundle_id to route:

{
  "type": "message.received",
  "data": {
    "message_type": "imessage_app",
    "text": "Requested Location",
    "sender": "+15551234567",
    "imessage_app": {
      "balloon_bundle_id": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.findmy.FindMyMessagesApp",
      "team_id": "0000000000",
      "bundle_id": "com.apple.findmy.FindMyMessagesApp",
      "app_name": "Find My",
      "caption": "Requested Location",
      "summary": "Requested Location",
      "url": "?FindMyMessagePayloadVersionKey=v0&FindMyMessagePayloadZippedDataKey=…"
    }
  }
}

Warning

The url carries Apple's end-to-end-encrypted session data (sharing invitation, iCloud share link, participant ids). You can relay a bubble you received, but a live session (real-time location, an active timer) requires a payload from a genuine Apple session — it can't be synthesized.

Related

• Custom bubbles (iMessage apps) — the generic mechanism
• Attachments & carousels
• Webhooks — subscribe to message.received