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.

Usage Instructions

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.

Tools

agentphone_create_call

Initiate an outbound voice call from an AgentPhone agent

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
agentIdstringYesAgent that will handle the call
toNumberstringYesPhone number to call in E.164 format (e.g. +14155551234)
fromNumberIdstringNoPhone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used.
initialGreetingstringNoOptional greeting spoken when the recipient answers
voicestringNoVoice ID override for this call (defaults to the agent's configured voice)
systemPromptstringNoWhen provided, uses a built-in LLM for the conversation instead of forwarding to your webhook

Output

ParameterTypeDescription
idstringUnique call identifier
agentIdstringAgent handling the call
statusstringInitial call status
toNumberstringDestination phone number
fromNumberstringCaller ID used for the call
phoneNumberIdstringID of the phone number used as caller ID
directionstringCall direction (outbound)
startedAtstringISO 8601 timestamp

agentphone_create_contact

Create a new contact in AgentPhone

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
phoneNumberstringYesPhone number in E.164 format (e.g. +14155551234)
namestringYesContact's full name
emailstringNoContact's email address
notesstringNoFreeform notes stored on the contact

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_create_number

Provision a new SMS- and voice-enabled phone number

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
countrystringNoTwo-letter country code (e.g. US, CA). Defaults to US.
areaCodestringNoPreferred area code (US/CA only, e.g. "415"). Best-effort — may be ignored if unavailable.
agentIdstringNoOptionally attach the number to an agent immediately

Output

ParameterTypeDescription
idstringUnique phone number ID
phoneNumberstringProvisioned phone number in E.164 format
countrystringTwo-letter country code
statusstringNumber status (e.g. active)
typestringNumber type (e.g. sms)
agentIdstringAgent the number is attached to
createdAtstringISO 8601 timestamp when the number was created

agentphone_delete_contact

Delete a contact by ID

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID

Output

ParameterTypeDescription
idstringID of the deleted contact
deletedbooleanWhether the contact was deleted successfully

agentphone_get_call

Fetch a call and its full transcript

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
callIdstringYesID of the call to retrieve

Output

ParameterTypeDescription
idstringCall ID
agentIdstringAgent that handled the call
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number used for the call
fromNumberstringCaller phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
statusstringCall status
startedAtstringISO 8601 timestamp
endedAtstringISO 8601 timestamp
durationSecondsnumberCall duration in seconds
lastTranscriptSnippetstringLast transcript snippet
recordingUrlstringRecording audio URL
recordingAvailablebooleanWhether a recording is available
transcriptsarrayOrdered transcript turns for the call
idstringTranscript turn ID
transcriptstringUser utterance
confidencenumberSpeech recognition confidence
responsestringAgent response (when available)
createdAtstringISO 8601 timestamp

agentphone_get_call_transcript

Get the full ordered transcript for a call

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
callIdstringYesID of the call to retrieve the transcript for

Output

ParameterTypeDescription
callIdstringCall ID
transcriptarrayOrdered transcript turns for the call
rolestringSpeaker role (user or agent)
contentstringTurn content
createdAtstringISO 8601 timestamp

agentphone_get_contact

Fetch a single contact by ID

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_get_conversation

Get a conversation along with its recent messages

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
messageLimitnumberNoNumber of recent messages to include (default 50, max 100)

Output

ParameterTypeDescription
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
messageCountnumberNumber of messages in the conversation
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
messagesarrayRecent messages in the conversation
idstringMessage ID
bodystringMessage text
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringsms, mms, or imessage
mediaUrlstringAttached media URL
receivedAtstringISO 8601 timestamp

agentphone_get_conversation_messages

Get paginated messages for a conversation

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
limitnumberNoNumber of messages to return (default 50, max 200)
beforestringNoReturn messages received before this ISO 8601 timestamp
afterstringNoReturn messages received after this ISO 8601 timestamp

Output

ParameterTypeDescription
dataarrayMessages in the conversation
idstringMessage ID
bodystringMessage text
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringsms, mms, or imessage
mediaUrlstringAttached media URL
receivedAtstringISO 8601 timestamp
hasMorebooleanWhether more messages are available

agentphone_get_number_messages

Fetch messages received on a specific phone number

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
numberIdstringYesID of the phone number
limitnumberNoNumber of messages to return (default 50, max 200)
beforestringNoReturn messages received before this ISO 8601 timestamp
afterstringNoReturn messages received after this ISO 8601 timestamp

Output

ParameterTypeDescription
dataarrayMessages received on the number
idstringMessage ID
from_stringSender phone number (E.164)
tostringRecipient phone number (E.164)
bodystringMessage text
directionstringinbound or outbound
channelstringChannel (sms, mms, etc.)
receivedAtstringISO 8601 timestamp
hasMorebooleanWhether more messages are available

agentphone_get_usage

Retrieve current usage statistics for the AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key

Output

ParameterTypeDescription
planjsonPlan name and limits (name, limits: numbers/messagesPerMonth/voiceMinutesPerMonth/maxCallDurationMinutes/concurrentCalls)
numbersjsonPhone number usage (used, limit, remaining)
statsjsonUsage stats: totalMessages, messagesLast24h/7d/30d, totalCalls, callsLast24h/7d/30d, totalWebhookDeliveries, successfulWebhookDeliveries, failedWebhookDeliveries
periodStartstringBilling period start
periodEndstringBilling period end

agentphone_get_usage_daily

Get a daily breakdown of usage (messages, calls, webhooks) for the last N days

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
daysnumberNoNumber of days to return (1-365, default 30)

Output

ParameterTypeDescription
dataarrayDaily usage entries
datestringDay (YYYY-MM-DD)
messagesnumberMessages that day
callsnumberCalls that day
webhooksnumberWebhook deliveries that day
daysnumberNumber of days returned

agentphone_get_usage_monthly

Get monthly usage aggregation (messages, calls, webhooks) for the last N months

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
monthsnumberNoNumber of months to return (1-24, default 6)

Output

ParameterTypeDescription
dataarrayMonthly usage entries
monthstringMonth (YYYY-MM)
messagesnumberMessages that month
callsnumberCalls that month
webhooksnumberWebhook deliveries that month
monthsnumberNumber of months returned

agentphone_list_calls

List voice calls for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)
statusstringNoFilter by status (completed, in-progress, failed)
directionstringNoFilter by direction (inbound, outbound)
typestringNoFilter by call type (pstn, web)
searchstringNoSearch by phone number (matches fromNumber or toNumber)

Output

ParameterTypeDescription
dataarrayCalls
idstringCall ID
agentIdstringAgent that handled the call
phoneNumberIdstringPhone number ID used for the call
phoneNumberstringPhone number used for the call
fromNumberstringCaller phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
statusstringCall status
startedAtstringISO 8601 timestamp
endedAtstringISO 8601 timestamp
durationSecondsnumberCall duration in seconds
lastTranscriptSnippetstringLast transcript snippet
recordingUrlstringRecording audio URL
recordingAvailablebooleanWhether a recording is available
hasMorebooleanWhether more results are available
totalnumberTotal number of matching calls

agentphone_list_contacts

List contacts for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
searchstringNoFilter by name or phone number (case-insensitive contains)
limitnumberNoNumber of results to return (default 50)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayContacts
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of contacts

agentphone_list_conversations

List conversations (message threads) for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayConversations
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
lastMessagePreviewstringLast message preview
messageCountnumberNumber of messages in the conversation
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of conversations

agentphone_list_numbers

List all phone numbers provisioned for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayPhone numbers
idstringPhone number ID
phoneNumberstringPhone number in E.164 format
countrystringTwo-letter country code
statusstringNumber status
typestringNumber type (e.g. sms)
agentIdstringAttached agent ID
createdAtstringISO 8601 creation timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of phone numbers

agentphone_react_to_message

Send an iMessage tapback reaction to a message (iMessage only)

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
messageIdstringYesID of the message to react to
reactionstringYesReaction type: love, like, dislike, laugh, emphasize, or question

Output

ParameterTypeDescription
idstringReaction ID
reactionTypestringReaction type applied
messageIdstringID of the message that was reacted to
channelstringChannel (imessage)

agentphone_release_number

Release (delete) a phone number. This action is irreversible.

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
numberIdstringYesID of the phone number to release

Output

ParameterTypeDescription
idstringID of the released phone number
releasedbooleanWhether the number was released successfully

agentphone_send_message

Send an outbound SMS or iMessage from an AgentPhone agent

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
agentIdstringYesAgent sending the message
toNumberstringYesRecipient phone number in E.164 format (e.g. +14155551234)
bodystringYesMessage text to send
mediaUrlstringNoOptional URL of an image, video, or file to attach
numberIdstringNoPhone number ID to send from. If omitted, the agent's first assigned number is used.

Output

ParameterTypeDescription
idstringMessage ID
statusstringDelivery status
channelstringsms, mms, or imessage
fromNumberstringSender phone number
toNumberstringRecipient phone number

agentphone_update_contact

Update a contact

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID
phoneNumberstringNoNew phone number in E.164 format
namestringNoNew contact name
emailstringNoNew email address
notesstringNoNew freeform notes

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_update_conversation

Update conversation metadata (stored state). Pass null to clear existing metadata.

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
metadatajsonNoCustom key-value metadata to store on the conversation. Pass null to clear existing metadata.

Output

ParameterTypeDescription
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
messageCountnumberNumber of messages
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
messagesarrayMessages in the conversation
idstringMessage ID
bodystringMessage body
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringChannel (sms, mms, etc.)
mediaUrlstringMedia URL if any
receivedAtstringISO 8601 timestamp

On this page