# iMessage

The platform supports iMessage as a messaging channel, enabling patient communication through Apple's native messaging experience. iMessage delivery provides blue-bubble messaging with read receipts, typing indicators, and rich media support on Apple devices.

## How It Works

iMessage channels are provisioned as subaccounts, each representing a distinct business identity. Each subaccount is assigned a dedicated phone number that patients see as the sender.

The provisioning flow:

1. **Create a setup** - Provide a business name and an operator-facing label. The platform provisions a subaccount with the upstream iMessage provider and securely stores the credentials.
2. **Phone line assignment** - A phone number is assigned to the subaccount. If a number is available immediately, it is included in the setup response. If the number requires carrier placement, the setup is created in a pending state and the number is assigned asynchronously.
3. **Line notification** - When a pending line is assigned, the platform receives a webhook notification and updates the setup automatically. No manual intervention is required.

## 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 happens automatically when the upstream provider places the number. Re-deliveries of assignment notifications are handled idempotently.

## Security

Per-subaccount credentials are stored securely and are never exposed through the API. Webhook deliveries are authenticated using a per-subaccount secret that is verified on every event. Both unknown-account and authentication-failure responses return identical errors to prevent account enumeration.

## Management

Setups can be listed and inspected through the API. The list view includes a phone line count per setup. The detail view includes the full phone line records with their assignment status.

iMessage setups do not require a separate compliance or brand registration workflow - provisioning is handled entirely through the subaccount creation process.


---

# Agent Instructions: 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:

```
GET https://docs.amigo.ai/channels/imessage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.