AgentPhone
Provision numbers, send SMS and iMessage, and place voice calls with AgentPhone
AgentPhone is an API-first voice and messaging platform built for AI agents. AgentPhone lets you provision real phone numbers, place outbound AI voice calls, send SMS and iMessage, manage conversations and contacts, and monitor usage — all through a simple REST API designed for programmatic access.
Why AgentPhone?
- Agent-Native Telephony: Purpose-built for AI agents — provision numbers, place calls, and send messages without carrier contracts or telephony plumbing.
- Voice + Messaging in One API: Drive outbound AI voice calls alongside SMS, MMS, and iMessage from the same account and phone numbers.
- Conversation & Transcript Management: Every call returns an ordered transcript; every message thread is tracked as a conversation with full history and metadata.
- Contacts Built In: Create, search, update, and delete contacts on the account so your agents can reference people by name instead of raw phone numbers.
- Usage Visibility: Inspect plan limits, current counts, and daily/monthly aggregation so workflows can stay inside guardrails.
Using AgentPhone in Sim
Sim's AgentPhone integration connects your agentic workflows directly to AgentPhone using an API key. With 22 operations spanning numbers, calls, conversations, contacts, and usage, you can build powerful voice and messaging automations without writing backend code.
Key benefits of using AgentPhone in Sim:
- Dynamic number provisioning: Reserve US or Canadian numbers on the fly — per agent, per customer, or per workflow — and release them when no longer needed.
- Outbound AI voice calls: Place calls from an agent with an optional greeting, voice override, or system prompt, and read the full transcript back as structured data once the call completes.
- Two-way messaging: Send SMS, MMS, or iMessage, fetch conversation history, and react to incoming iMessages — all from inside your workflow.
- Contact and metadata management: Keep an account-level contact list and attach custom JSON metadata to conversations so downstream blocks can branch on state.
- Operational insight: Pull current usage stats and daily/monthly breakdowns to monitor consumption and enforce plan limits before making the next call.
Whether you're building an outbound AI voice agent, running automated SMS follow-ups, managing two-way customer conversations, or monitoring phone usage across your organization, AgentPhone in Sim gives you direct, secure access to the full AgentPhone API — no middleware required. Simply configure your API key, select the operation you need, and let Sim handle the rest.
Give your workflow a phone. Provision SMS- and voice-enabled numbers, send messages and tapback reactions, place outbound voice calls, manage conversations and contacts, and track usage — all through a single AgentPhone API key.
Initiate an outbound voice call from an AgentPhone agent
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
agentId | string | Yes | Agent that will handle the call |
toNumber | string | Yes | Phone number to call in E.164 format (e.g. +14155551234) |
fromNumberId | string | No | Phone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used. |
initialGreeting | string | No | Optional greeting spoken when the recipient answers |
voice | string | No | Voice ID override for this call (defaults to the agent's configured voice) |
systemPrompt | string | No | When provided, uses a built-in LLM for the conversation instead of forwarding to your webhook |
| Parameter | Type | Description |
|---|
id | string | Unique call identifier |
agentId | string | Agent handling the call |
status | string | Initial call status |
toNumber | string | Destination phone number |
fromNumber | string | Caller ID used for the call |
phoneNumberId | string | ID of the phone number used as caller ID |
direction | string | Call direction (outbound) |
startedAt | string | ISO 8601 timestamp |
Create a new contact in AgentPhone
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
phoneNumber | string | Yes | Phone number in E.164 format (e.g. +14155551234) |
name | string | Yes | Contact's full name |
email | string | No | Contact's email address |
notes | string | No | Freeform notes stored on the contact |
| Parameter | Type | Description |
|---|
id | string | Contact ID |
phoneNumber | string | Phone number in E.164 format |
name | string | Contact name |
email | string | Contact email address |
notes | string | Freeform notes |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 update timestamp |
Provision a new SMS- and voice-enabled phone number
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
country | string | No | Two-letter country code (e.g. US, CA). Defaults to US. |
areaCode | string | No | Preferred area code (US/CA only, e.g. "415"). Best-effort — may be ignored if unavailable. |
agentId | string | No | Optionally attach the number to an agent immediately |
| Parameter | Type | Description |
|---|
id | string | Unique phone number ID |
phoneNumber | string | Provisioned phone number in E.164 format |
country | string | Two-letter country code |
status | string | Number status (e.g. active) |
type | string | Number type (e.g. sms) |
agentId | string | Agent the number is attached to |
createdAt | string | ISO 8601 timestamp when the number was created |
Delete a contact by ID
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
contactId | string | Yes | Contact ID |
| Parameter | Type | Description |
|---|
id | string | ID of the deleted contact |
deleted | boolean | Whether the contact was deleted successfully |
Fetch a call and its full transcript
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
callId | string | Yes | ID of the call to retrieve |
| Parameter | Type | Description |
|---|
id | string | Call ID |
agentId | string | Agent that handled the call |
phoneNumberId | string | Phone number ID |
phoneNumber | string | Phone number used for the call |
fromNumber | string | Caller phone number |
toNumber | string | Recipient phone number |
direction | string | inbound or outbound |
status | string | Call status |
startedAt | string | ISO 8601 timestamp |
endedAt | string | ISO 8601 timestamp |
durationSeconds | number | Call duration in seconds |
lastTranscriptSnippet | string | Last transcript snippet |
recordingUrl | string | Recording audio URL |
recordingAvailable | boolean | Whether a recording is available |
transcripts | array | Ordered transcript turns for the call |
↳ id | string | Transcript turn ID |
↳ transcript | string | User utterance |
↳ confidence | number | Speech recognition confidence |
↳ response | string | Agent response (when available) |
↳ createdAt | string | ISO 8601 timestamp |
Get the full ordered transcript for a call
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
callId | string | Yes | ID of the call to retrieve the transcript for |
| Parameter | Type | Description |
|---|
callId | string | Call ID |
transcript | array | Ordered transcript turns for the call |
↳ role | string | Speaker role (user or agent) |
↳ content | string | Turn content |
↳ createdAt | string | ISO 8601 timestamp |
Fetch a single contact by ID
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
contactId | string | Yes | Contact ID |
| Parameter | Type | Description |
|---|
id | string | Contact ID |
phoneNumber | string | Phone number in E.164 format |
name | string | Contact name |
email | string | Contact email address |
notes | string | Freeform notes |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 update timestamp |
Get a conversation along with its recent messages
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
conversationId | string | Yes | Conversation ID |
messageLimit | number | No | Number of recent messages to include (default 50, max 100) |
| Parameter | Type | Description |
|---|
id | string | Conversation ID |
agentId | string | Agent ID |
phoneNumberId | string | Phone number ID |
phoneNumber | string | Phone number |
participant | string | External participant phone number |
lastMessageAt | string | ISO 8601 timestamp |
messageCount | number | Number of messages in the conversation |
metadata | json | Custom metadata stored on the conversation |
createdAt | string | ISO 8601 timestamp |
messages | array | Recent messages in the conversation |
↳ id | string | Message ID |
↳ body | string | Message text |
↳ fromNumber | string | Sender phone number |
↳ toNumber | string | Recipient phone number |
↳ direction | string | inbound or outbound |
↳ channel | string | sms, mms, or imessage |
↳ mediaUrl | string | Attached media URL |
↳ receivedAt | string | ISO 8601 timestamp |
Get paginated messages for a conversation
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
conversationId | string | Yes | Conversation ID |
limit | number | No | Number of messages to return (default 50, max 200) |
before | string | No | Return messages received before this ISO 8601 timestamp |
after | string | No | Return messages received after this ISO 8601 timestamp |
| Parameter | Type | Description |
|---|
data | array | Messages in the conversation |
↳ id | string | Message ID |
↳ body | string | Message text |
↳ fromNumber | string | Sender phone number |
↳ toNumber | string | Recipient phone number |
↳ direction | string | inbound or outbound |
↳ channel | string | sms, mms, or imessage |
↳ mediaUrl | string | Attached media URL |
↳ receivedAt | string | ISO 8601 timestamp |
hasMore | boolean | Whether more messages are available |
Fetch messages received on a specific phone number
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
numberId | string | Yes | ID of the phone number |
limit | number | No | Number of messages to return (default 50, max 200) |
before | string | No | Return messages received before this ISO 8601 timestamp |
after | string | No | Return messages received after this ISO 8601 timestamp |
| Parameter | Type | Description |
|---|
data | array | Messages received on the number |
↳ id | string | Message ID |
↳ from_ | string | Sender phone number (E.164) |
↳ to | string | Recipient phone number (E.164) |
↳ body | string | Message text |
↳ direction | string | inbound or outbound |
↳ channel | string | Channel (sms, mms, etc.) |
↳ receivedAt | string | ISO 8601 timestamp |
hasMore | boolean | Whether more messages are available |
Retrieve current usage statistics for the AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
| Parameter | Type | Description |
|---|
plan | json | Plan name and limits (name, limits: numbers/messagesPerMonth/voiceMinutesPerMonth/maxCallDurationMinutes/concurrentCalls) |
numbers | json | Phone number usage (used, limit, remaining) |
stats | json | Usage stats: totalMessages, messagesLast24h/7d/30d, totalCalls, callsLast24h/7d/30d, totalWebhookDeliveries, successfulWebhookDeliveries, failedWebhookDeliveries |
periodStart | string | Billing period start |
periodEnd | string | Billing period end |
Get a daily breakdown of usage (messages, calls, webhooks) for the last N days
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
days | number | No | Number of days to return (1-365, default 30) |
| Parameter | Type | Description |
|---|
data | array | Daily usage entries |
↳ date | string | Day (YYYY-MM-DD) |
↳ messages | number | Messages that day |
↳ calls | number | Calls that day |
↳ webhooks | number | Webhook deliveries that day |
days | number | Number of days returned |
Get monthly usage aggregation (messages, calls, webhooks) for the last N months
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
months | number | No | Number of months to return (1-24, default 6) |
| Parameter | Type | Description |
|---|
data | array | Monthly usage entries |
↳ month | string | Month (YYYY-MM) |
↳ messages | number | Messages that month |
↳ calls | number | Calls that month |
↳ webhooks | number | Webhook deliveries that month |
months | number | Number of months returned |
List voice calls for this AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
limit | number | No | Number of results to return (default 20, max 100) |
offset | number | No | Number of results to skip (min 0) |
status | string | No | Filter by status (completed, in-progress, failed) |
direction | string | No | Filter by direction (inbound, outbound) |
type | string | No | Filter by call type (pstn, web) |
search | string | No | Search by phone number (matches fromNumber or toNumber) |
| Parameter | Type | Description |
|---|
data | array | Calls |
↳ id | string | Call ID |
↳ agentId | string | Agent that handled the call |
↳ phoneNumberId | string | Phone number ID used for the call |
↳ phoneNumber | string | Phone number used for the call |
↳ fromNumber | string | Caller phone number |
↳ toNumber | string | Recipient phone number |
↳ direction | string | inbound or outbound |
↳ status | string | Call status |
↳ startedAt | string | ISO 8601 timestamp |
↳ endedAt | string | ISO 8601 timestamp |
↳ durationSeconds | number | Call duration in seconds |
↳ lastTranscriptSnippet | string | Last transcript snippet |
↳ recordingUrl | string | Recording audio URL |
↳ recordingAvailable | boolean | Whether a recording is available |
hasMore | boolean | Whether more results are available |
total | number | Total number of matching calls |
List contacts for this AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
search | string | No | Filter by name or phone number (case-insensitive contains) |
limit | number | No | Number of results to return (default 50) |
offset | number | No | Number of results to skip (min 0) |
| Parameter | Type | Description |
|---|
data | array | Contacts |
↳ id | string | Contact ID |
↳ phoneNumber | string | Phone number in E.164 format |
↳ name | string | Contact name |
↳ email | string | Contact email address |
↳ notes | string | Freeform notes |
↳ createdAt | string | ISO 8601 creation timestamp |
↳ updatedAt | string | ISO 8601 update timestamp |
hasMore | boolean | Whether more results are available |
total | number | Total number of contacts |
List conversations (message threads) for this AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
limit | number | No | Number of results to return (default 20, max 100) |
offset | number | No | Number of results to skip (min 0) |
| Parameter | Type | Description |
|---|
data | array | Conversations |
↳ id | string | Conversation ID |
↳ agentId | string | Agent ID |
↳ phoneNumberId | string | Phone number ID |
↳ phoneNumber | string | Phone number |
↳ participant | string | External participant phone number |
↳ lastMessageAt | string | ISO 8601 timestamp |
↳ lastMessagePreview | string | Last message preview |
↳ messageCount | number | Number of messages in the conversation |
↳ metadata | json | Custom metadata stored on the conversation |
↳ createdAt | string | ISO 8601 timestamp |
hasMore | boolean | Whether more results are available |
total | number | Total number of conversations |
List all phone numbers provisioned for this AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
limit | number | No | Number of results to return (default 20, max 100) |
offset | number | No | Number of results to skip (min 0) |
| Parameter | Type | Description |
|---|
data | array | Phone numbers |
↳ id | string | Phone number ID |
↳ phoneNumber | string | Phone number in E.164 format |
↳ country | string | Two-letter country code |
↳ status | string | Number status |
↳ type | string | Number type (e.g. sms) |
↳ agentId | string | Attached agent ID |
↳ createdAt | string | ISO 8601 creation timestamp |
hasMore | boolean | Whether more results are available |
total | number | Total number of phone numbers |
Send an iMessage tapback reaction to a message (iMessage only)
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
messageId | string | Yes | ID of the message to react to |
reaction | string | Yes | Reaction type: love, like, dislike, laugh, emphasize, or question |
| Parameter | Type | Description |
|---|
id | string | Reaction ID |
reactionType | string | Reaction type applied |
messageId | string | ID of the message that was reacted to |
channel | string | Channel (imessage) |
Release (delete) a phone number. This action is irreversible.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
numberId | string | Yes | ID of the phone number to release |
| Parameter | Type | Description |
|---|
id | string | ID of the released phone number |
released | boolean | Whether the number was released successfully |
Send an outbound SMS or iMessage from an AgentPhone agent
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
agentId | string | Yes | Agent sending the message |
toNumber | string | Yes | Recipient phone number in E.164 format (e.g. +14155551234) |
body | string | Yes | Message text to send |
mediaUrl | string | No | Optional URL of an image, video, or file to attach |
numberId | string | No | Phone number ID to send from. If omitted, the agent's first assigned number is used. |
| Parameter | Type | Description |
|---|
id | string | Message ID |
status | string | Delivery status |
channel | string | sms, mms, or imessage |
fromNumber | string | Sender phone number |
toNumber | string | Recipient phone number |
Update a contact
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
contactId | string | Yes | Contact ID |
phoneNumber | string | No | New phone number in E.164 format |
name | string | No | New contact name |
email | string | No | New email address |
notes | string | No | New freeform notes |
| Parameter | Type | Description |
|---|
id | string | Contact ID |
phoneNumber | string | Phone number in E.164 format |
name | string | Contact name |
email | string | Contact email address |
notes | string | Freeform notes |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 update timestamp |
Update conversation metadata (stored state). Pass null to clear existing metadata.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
conversationId | string | Yes | Conversation ID |
metadata | json | No | Custom key-value metadata to store on the conversation. Pass null to clear existing metadata. |
| Parameter | Type | Description |
|---|
id | string | Conversation ID |
agentId | string | Agent ID |
phoneNumberId | string | Phone number ID |
phoneNumber | string | Phone number |
participant | string | External participant phone number |
lastMessageAt | string | ISO 8601 timestamp |
messageCount | number | Number of messages |
metadata | json | Custom metadata stored on the conversation |
createdAt | string | ISO 8601 timestamp |
messages | array | Messages in the conversation |
↳ id | string | Message ID |
↳ body | string | Message body |
↳ fromNumber | string | Sender phone number |
↳ toNumber | string | Recipient phone number |
↳ direction | string | inbound or outbound |
↳ channel | string | Channel (sms, mms, etc.) |
↳ mediaUrl | string | Media URL if any |
↳ receivedAt | string | ISO 8601 timestamp |