iMessage

iMessage channel for patient communication through Apple's messaging platform.

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.