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

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

Output

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 Contact

Create a new contact in AgentPhone

Inputs and outputs

Input

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

Output

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

Create Phone Number

Provision a new SMS- and voice-enabled phone number

Inputs and outputs

Input

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

Output

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 Contact

Delete a contact by ID

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`contactId`	string	Yes	Contact ID

Output

Parameter	Type	Description
`id`	string	ID of the deleted contact
`deleted`	boolean	Whether the contact was deleted successfully

Get Call

Fetch a call and its full transcript

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`callId`	string	Yes	ID of the call to retrieve

Output

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 Call Transcript

Get the full ordered transcript for a call

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`callId`	string	Yes	ID of the call to retrieve the transcript for

Output

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

Get Contact

Fetch a single contact by ID

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`contactId`	string	Yes	Contact ID

Output

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 Conversation

Get a conversation along with its recent messages

Inputs and outputs

Input

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)

Output

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
↳ `mediaUrls`	array	All attached media URLs
↳ `receivedAt`	string	ISO 8601 timestamp

Get Conversation Messages

Get paginated messages for a conversation

Inputs and outputs

Input

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

Output

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
↳ `mediaUrls`	array	All attached media URLs
↳ `receivedAt`	string	ISO 8601 timestamp
`hasMore`	boolean	Whether more messages are available

Get Phone Number Messages

Fetch messages received on a specific phone number

Inputs and outputs

Input

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

Output

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

Get Usage

Retrieve current usage statistics for the AgentPhone account

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key

Output

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 Daily Usage

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

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`days`	number	No	Number of days to return (1-365, default 30)

Output

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

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

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`months`	number	No	Number of months to return (1-24, default 6)

Output

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 Calls

List voice calls for this AgentPhone account

Inputs and outputs

Input

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)

Output

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

List contacts for this AgentPhone account

Inputs and outputs

Input

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, max 200)
`offset`	number	No	Number of results to skip (min 0)

Output

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

List conversations (message threads) for this AgentPhone account

Inputs and outputs

Input

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)

Output

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 Phone Numbers

List all phone numbers provisioned for this AgentPhone account

Inputs and outputs

Input

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)

Output

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

React to Message

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

Inputs and outputs

Input

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

Output

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 Phone Number

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

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	AgentPhone API key
`numberId`	string	Yes	ID of the phone number to release

Output

Parameter	Type	Description
`id`	string	ID of the released phone number
`released`	boolean	Whether the number was released successfully

Send Message

Send an outbound SMS or iMessage from an AgentPhone agent

Inputs and outputs

Input

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.

Output

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 Contact

Update a contact's fields

Inputs and outputs

Input

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

Output

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

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

Inputs and outputs

Input

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.

Output

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
↳ `mediaUrls`	array	All attached media URLs
↳ `receivedAt`	string	ISO 8601 timestamp

AgentMail Agiloft