AgentPhone

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

Instrucciones de uso

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.

Herramientas

`agentphone_create_call`

Initiate an outbound voice call from an AgentPhone agent

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`agentId`	string	Sí	Agent that will handle the call
`toNumber`	string	Sí	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

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`phoneNumber`	string	Sí	Phone number in E.164 format (e.g. +14155551234)
`name`	string	Sí	Contact's full name
`email`	string	No	Contact's email address
`notes`	string	No	Freeform notes stored on the contact

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	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

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`contactId`	string	Sí	Contact ID

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`callId`	string	Sí	ID of the call to retrieve

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_call_transcript`

Get the full ordered transcript for a call

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`callId`	string	Sí	ID of the call to retrieve the transcript for

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_contact`

Fetch a single contact by ID

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`contactId`	string	Sí	Contact ID

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`conversationId`	string	Sí	Conversation ID
`messageLimit`	number	No	Number of recent messages to include (default 50, max 100)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_conversation_messages`

Get paginated messages for a conversation

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`conversationId`	string	Sí	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

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_number_messages`

Fetch messages received on a specific phone number

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`numberId`	string	Sí	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

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_usage`

Retrieve current usage statistics for the AgentPhone account

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`days`	number	No	Number of days to return (1-365, default 30)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_get_usage_monthly`

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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`months`	number	No	Number of months to return (1-24, default 6)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_list_calls`

List voice calls for this AgentPhone account

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	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)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_list_contacts`

List contacts for this AgentPhone account

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	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)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_list_conversations`

List conversations (message threads) for this AgentPhone account

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	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)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_list_numbers`

List all phone numbers provisioned for this AgentPhone account

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	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)

Salida

Parámetro	Tipo	Descripción
`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

`agentphone_react_to_message`

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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`messageId`	string	Sí	ID of the message to react to
`reaction`	string	Sí	Reaction type: love, like, dislike, laugh, emphasize, or question

Salida

Parámetro	Tipo	Descripción
`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.

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`numberId`	string	Sí	ID of the phone number to release

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`agentId`	string	Sí	Agent sending the message
`toNumber`	string	Sí	Recipient phone number in E.164 format (e.g. +14155551234)
`body`	string	Sí	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.

Salida

Parámetro	Tipo	Descripción
`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

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`contactId`	string	Sí	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

Salida

Parámetro	Tipo	Descripción
`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.

Entrada

Parámetro	Tipo	Obligatorio	Descripción
`apiKey`	string	Sí	AgentPhone API key
`conversationId`	string	Sí	Conversation ID
`metadata`	json	No	Custom key-value metadata to store on the conversation. Pass null to clear existing metadata.

Salida

Parámetro	Tipo	Descripción
`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

On this page

Instrucciones de uso

agentphone_create_call

agentphone_create_contact

agentphone_create_number

agentphone_delete_contact

agentphone_get_call

agentphone_get_call_transcript

agentphone_get_contact

agentphone_get_conversation

agentphone_get_conversation_messages

agentphone_get_number_messages

agentphone_get_usage

agentphone_get_usage_daily

agentphone_get_usage_monthly

agentphone_list_calls

agentphone_list_contacts

agentphone_list_conversations

agentphone_list_numbers

agentphone_react_to_message

agentphone_release_number

agentphone_send_message

agentphone_update_contact

agentphone_update_conversation