Set up iMessage

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

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 before purchasing. See Usage & Billing.

Purchase a number

In the dashboard, open 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:

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 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.

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, 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 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.

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 and Troubleshooting before building automated follow-ups.

Once the basic exchange works, add media, reactions, and groups or a contact card.