> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/channels/imessage.md). # iMessage 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: 1. **Registers the managed setup** - Associates the workspace's business identity with the channel provider. 2. **Assigns a phone line** - Uses an available number or waits for asynchronous line placement. 3. **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](/channels/email.md#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](/channels/text-sessions.md#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](/channels/outbound.md) 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 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, use Platform API use-case inventory and service-binding operations for workspace routing, and contact Amigo for upstream setup changes. {% content-ref url="/pages/F9G0lrxZA31mW1pawkgs" %} [Text Sessions](/channels/text-sessions.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/channels/imessage.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.