> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server.

# Set up iMessage

> Purchase the right iMessage line, handle asynchronous provisioning, and send your first message.

An iMessage line is a separate number type. Buying a standard SMS number or selecting a hosted voice agent does not enable iMessage on that number.

## Choose a line

| Line     | Starts a conversation                      | Replies to inbound messages               | Standard monthly price |
| -------- | ------------------------------------------ | ----------------------------------------- | ---------------------- |
| Inbound  | No; the recipient must text the line first | Yes, subject to conversation restrictions | \$150                  |
| Outbound | Yes, up to 50 new contacts/day/line        | Yes, subject to conversation restrictions | \$250                  |

iMessage line subscriptions charge the card on file, separately from your prepaid credit balance. Account-specific pricing may apply. Add a payment method in [Billing](https://agentphone.ai/billing) before purchasing. See [Usage & Billing](/usage).

## Purchase a number

In the dashboard, open [Numbers](https://agentphone.ai/numbers) and choose **Get an iMessage Number**. Follow the order's status and readiness message.

Through the API, omit `areaCode` to request an available line:

```bash
curl --fail-with-body "https://api.agentphone.ai/v1/numbers" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"imessage","imessageType":"outbound","agentId":"YOUR_AGENT_ID"}'
```

`imessageType` defaults to `outbound`; explicitly use `inbound` for a reply-only line. `agentId` is optional, but attaching to an agent makes webhook routing straightforward.

### Handle both success responses

* **`200` with `id` and `phoneNumber`:** the line was allocated from available inventory. Save the number ID.
* **`202` with `status: "provisioning"` and `requestId`:** an order was accepted but the number is not ready. The response includes `amountChargedCents` and a readiness message. The request ID is not a number ID. Wait for fulfillment and use the number returned by `GET /v1/numbers` or the dashboard.

A specific `areaCode` uses asynchronous provisioning and adds a \$75 one-time setup fee to the first month's subscription. Availability can also cause an order without an area code to take the asynchronous path. Read the response; do not repeatedly purchase while waiting for a line. See the [number creation reference](/api-reference) for the request fields.

## Send a first text

Use the provisioned number ID to make the sender explicit. Replace the recipient with your own mobile number for testing.

```bash
curl --fail-with-body "https://api.agentphone.ai/v1/messages" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number_id":"YOUR_NUMBER_ID","to_number":"+14155550123","body":"Hello from my AgentPhone line."}'
```

On an inbound line, have the recipient message you first. For a new outbound conversation, start with plain text: links and attachments may be rejected until the recipient sends a written reply. A reaction alone is not that reply.

Your line can reach supported non-iMessage recipients through its fallback transport. This differs from [branded RCS](/documentation/guides/rcs), which requires separate onboarding. Do not infer the recipient's final transport solely from a send response's `channel`; inspect delivery history and available capabilities.

## Receive and reply

Configure a [webhook](/documentation/guides/webhooks) in the same account or on the attached agent. Inbound texts arrive as `agent.message`; your backend sends replies using `POST /v1/messages`. Hosted voice mode does not supply a text chatbot.

For one-to-one replies, preserve `data.numberId` as the sender and use `data.from` as the recipient. For a group, reply to `data.group.groupId`; see [Group chats](/documentation/guides/messages#group-chats).

## Limits and pauses

The standard outbound ceiling is **50 new contacts per day per line**. Do not plan on raising it. Check `dailyNewContacts` on the number response when available; a `null` limit means it is not currently reported, not unlimited capacity.

Daily limits, consecutive-message limits, and messaging safety pauses are separate. Waiting for a daily reset does not clear a conversation that needs a recipient reply. Read [Messaging rate limits](/documentation/reference/messaging-rate-limits#imessage) and [Troubleshooting](/troubleshooting) before building automated follow-ups.

Once the basic exchange works, add [media, reactions, and groups](/documentation/guides/messages#imessage) or a [contact card](/api-reference).