Skip to content
Try for free
On this page

Integrations

AgentPhone

Provision numbers, send SMS and iMessage, and place voice calls with AgentPhone

Use AgentPhone to provision phone numbers, place outbound voice calls, send SMS or iMessage, and manage contacts and conversations from a workflow. Connect with an AgentPhone API key.

Retrieve call transcripts and conversation history for downstream processing, and check usage before starting more calls or messages.

Use the block

Provision SMS- and voice-enabled numbers, send messages and tapback reactions, place outbound calls, manage conversations and contacts, and inspect usage with an AgentPhone API key.

Actions

Create Outbound Call

Initiate an outbound voice call from an AgentPhone agent

Inputs and outputs

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

Create Contact

Create a new contact in AgentPhone

Inputs and outputs

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

Create Phone Number

Provision a new SMS- and voice-enabled phone number

Inputs and outputs

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

Delete Contact

Delete a contact by ID

Inputs and outputs

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID

Output

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

Get Call

Fetch a call and its full transcript

Inputs and outputs

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

Get Call Transcript

Get the full ordered transcript for a call

Inputs and outputs

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

Get Contact

Fetch a single contact by ID

Inputs and outputs

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

Get Conversation

Get a conversation along with its recent messages

Inputs and outputs

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
↳ mediaUrlsarrayAll attached media URLs
↳ receivedAtstringISO 8601 timestamp

Get Conversation Messages

Get paginated messages for a conversation

Inputs and outputs

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
↳ mediaUrlsarrayAll attached media URLs
↳ receivedAtstringISO 8601 timestamp
hasMorebooleanWhether more messages are available

Get Phone Number Messages

Fetch messages received on a specific phone number

Inputs and outputs

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

Get Usage

Retrieve current usage statistics for the AgentPhone account

Inputs and outputs

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

Get Daily Usage

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

Inputs and outputs

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

Get Monthly Usage

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

Inputs and outputs

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

List Calls

List voice calls for this AgentPhone account

Inputs and outputs

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

List Contacts

List contacts for this AgentPhone account

Inputs and outputs

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
searchstringNoFilter by name or phone number (case-insensitive contains)
limitnumberNoNumber of results to return (default 50, max 200)
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

List Conversations

List conversations (message threads) for this AgentPhone account

Inputs and outputs

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

List Phone Numbers

List all phone numbers provisioned for this AgentPhone account

Inputs and outputs

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

React to Message

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

Inputs and outputs

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)

Release Phone Number

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

Inputs and outputs

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

Send Message

Send an outbound SMS or iMessage from an AgentPhone agent

Inputs and outputs

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

Update Contact

Update a contact's fields

Inputs and outputs

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

Update Conversation

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

Inputs and outputs

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
↳ mediaUrlsarrayAll attached media URLs
↳ receivedAtstringISO 8601 timestamp
Was this helpful?
Suggest an edit