Tools

AgentPhone

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

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

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

`agentphone_create_contact`

Create a new contact in AgentPhone

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

`agentphone_create_number`

Provision a new SMS- and voice-enabled phone number

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

`agentphone_delete_contact`

Delete a contact by ID

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

`agentphone_get_call`

Fetch a call and its full transcript

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

`agentphone_get_call_transcript`

Get the full ordered transcript for a call

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

`agentphone_get_contact`

Fetch a single contact by ID

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

`agentphone_get_conversation`

Get a conversation along with its recent messages

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

`agentphone_get_conversation_messages`

Get paginated messages for a conversation

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
`hasMore`	boolean	Whether more messages are available

`agentphone_get_number_messages`

Fetch messages received on a specific phone number

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
`hasMore`	boolean	Whether more messages are available

`agentphone_get_usage`

Retrieve current usage statistics for the AgentPhone account

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

`agentphone_get_usage_daily`

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

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
`days`	number	Number of days returned

`agentphone_get_usage_monthly`

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

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
`months`	number	Number of months returned

`agentphone_list_calls`

List voice calls for this AgentPhone account

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
`hasMore`	boolean	Whether more results are available
`total`	number	Total number of matching calls

`agentphone_list_contacts`

List contacts for this AgentPhone account

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
`hasMore`	boolean	Whether more results are available
`total`	number	Total number of contacts

`agentphone_list_conversations`

List conversations (message threads) for this AgentPhone account

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
`hasMore`	boolean	Whether more results are available
`total`	number	Total number of conversations

`agentphone_list_numbers`

List all phone numbers provisioned for this AgentPhone account

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
`hasMore`	boolean	Whether more results are available
`total`	number	Total number of phone numbers

`agentphone_react_to_message`

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

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)

`agentphone_release_number`

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

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

`agentphone_send_message`

Send an outbound SMS or iMessage from an AgentPhone agent

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

`agentphone_update_contact`

Update a contact's fields

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

`agentphone_update_conversation`

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

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

Notes

Category: tools
Type: agentphone

AgentMail Agiloft

On this page

On this page

AgentPhone