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 Amigo account team to request access.
After provisioning, the Platform API can list workspace-owned use cases and bind an eligible iMessage use case to a service. It 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 Amigo 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.
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 Amigo workspace is configured for healthcare or because the device displays an encrypted conversation. Confirm the permitted use with the Amigo team before launch.
For sensitive collection, a workflow can send a minimal notification with a link to a Surface, 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 Amigo for upstream setup changes.
Last updated
Was this helpful?