iMessage
iMessage channel for patient communication through Apple's messaging platform.
The platform supports iMessage as a managed messaging channel for patient communication through Apple's native messaging experience. The channel records delivery status and supports text plus bounded media payloads on compatible devices.
Provisioning
Like SMS, iMessage provisioning is operator managed rather than self-service through the Platform API or Developer Console. It includes business identity, provider, and phone-line configuration. Timing depends on provider and carrier readiness. Contact your Concurrence account team to request access.
After provisioning, the Platform API can inspect service bindings and bind an eligible iMessage use case to a service. Provisioned use-case inventory belongs to the separate Channel Manager API. The Platform API does not create or delete the upstream provider setup or phone line for the workspace.
What Happens During Provisioning
iMessage is provisioned with a managed business identity and phone line. During setup, the Concurrence team:
Registers the managed setup - Associates the workspace's business identity with the channel provider.
Assigns a phone line - Uses an available number or waits for asynchronous line placement.
Binds the use case - Makes the provisioned channel available to the selected Platform service.
Phone Line Lifecycle
Each setup includes one or more phone lines. A phone line is in one of two states:
Pending - The line has been requested but a phone number has not yet been placed. The setup tracks the outstanding request.
Assigned - The line has a phone number in E.164 format and is ready for messaging.
The transition from pending to assigned is asynchronous. Do not send until the managed setup reports an assigned line.
Inbound iMessage
Inbound iMessage conversations follow the same durable processing model as SMS: messages from the same caller on the same use case are serialized onto the current non-terminal conversation. Replies can include supported text or bounded media payloads.
When a reply depends on supported background work, the asynchronous channel policy suppresses the intermediate acknowledgement and attempts to re-drive the final reply. Provider acceptance and delivery remain separate; inspect status rather than assuming the recipient received it. See Long-Running Tools and Reply Delivery.
Starting a Fresh Conversation
Because iMessage conversations are durable, a caller who messages the same number later can resume the current non-terminal thread - there is no reset keyword. If your application has the conversation ID, it can close that conversation through the lifecycle API. For a new outbound opener, create the iMessage conversation with force_new: true; the platform closes the active thread for the same recipient and use case before creating the new one. See Phone-Keyed Threads.
Outbound and Channel Switching
iMessage conversations can be started proactively (outbound) through the conversation lifecycle API by specifying iMessage as the channel, a recipient phone number in E.164 format, and a use case that determines the sender pool. The sender is resolved from the use case configuration - it is never supplied by the caller. See Outbound for details on the channel-generic lifecycle.
An active conversation on another channel (such as SMS) can be switched to iMessage, preserving the full conversation history. Each turn records which channel it occurred on, so the history is self-describing across channel changes.
First-Reply Limits and Opt-Out
The sender pool prefers an available line the recipient has already replied to, then the line most recently used for that recipient. If neither exists, it selects another available line. Your application does not choose a different line to avoid restrictions.
Before the recipient replies to the selected line, outbound messages are limited to 300 characters, no media, and no links, phone numbers, or email addresses. At most six messages recorded as sent or delivered may precede that first reply. A rejected attempt does not establish delivery. Check the returned error and wait for the recipient’s reply rather than rotating senders or repeating the same blocked request.
Supported opt-out keywords, including STOP, suppress sends to that recipient across the managed setup. START clears this iMessage suppression. This is a different contract from SMS’s separate line and setup controls. A successful send is still separate from delivery, and provider routing can fall back to SMS; confirm that fallback is acceptable for the workflow.
Security and Management Boundary
Channel selection must account for the intended content and contractual coverage. Do not infer that iMessage is covered for PHI because the Concurrence workspace is configured for healthcare or because the device displays an encrypted conversation. Confirm the permitted use with the Concurrence team before launch.
For sensitive collection, a workflow can send a minimal notification with a link to a Surface once the recipient has replied and the link is permitted, where the patient supplies the required information in a browser. The message body, link, form, access policy, and destination still need to match the deployment's data-handling requirements. A form link does not make PHI already included in the message safe to send.
Provider credentials, line placement, and inbound provider authentication remain inside managed channel infrastructure. Workspace applications use Platform credentials and the public conversation lifecycle; they do not receive provider secrets. After provisioning, bind the provisioned use case to a service through the Platform API for workspace routing, and contact Concurrence for upstream setup changes.
Last updated
Was this helpful?