# AgentPhone (/integrations/agentphone)





{/* MANUAL-CONTENT-START:intro */}

Use [AgentPhone](https://agentphone.to/) 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.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

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 [#actions]

### Create Outbound Call [#create-outbound-call]

Initiate an outbound voice call from an AgentPhone agent

<ReferenceDetails>
  #### Input [#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 [#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 |
</ReferenceDetails>

### Create Contact [#create-contact]

Create a new contact in AgentPhone

<ReferenceDetails>
  #### Input [#input-1]

  | 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 [#output-1]

  | 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 |
</ReferenceDetails>

### Create Phone Number [#create-phone-number]

Provision a new SMS- and voice-enabled phone number

<ReferenceDetails>
  #### Input [#input-2]

  | 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 [#output-2]

  | 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 |
</ReferenceDetails>

### Delete Contact [#delete-contact]

Delete a contact by ID

<ReferenceDetails>
  #### Input [#input-3]

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

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | ID of the deleted contact |
  | `deleted` | boolean | Whether the contact was deleted successfully |
</ReferenceDetails>

### Get Call [#get-call]

Fetch a call and its full transcript

<ReferenceDetails>
  #### Input [#input-4]

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

  #### Output [#output-4]

  | 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 |
</ReferenceDetails>

### Get Call Transcript [#get-call-transcript]

Get the full ordered transcript for a call

<ReferenceDetails>
  #### Input [#input-5]

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

  #### Output [#output-5]

  | 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 |
</ReferenceDetails>

### Get Contact [#get-contact]

Fetch a single contact by ID

<ReferenceDetails>
  #### Input [#input-6]

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

  #### Output [#output-6]

  | 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 |
</ReferenceDetails>

### Get Conversation [#get-conversation]

Get a conversation along with its recent messages

<ReferenceDetails>
  #### Input [#input-7]

  | 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 [#output-7]

  | 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 |
</ReferenceDetails>

### Get Conversation Messages [#get-conversation-messages]

Get paginated messages for a conversation

<ReferenceDetails>
  #### Input [#input-8]

  | 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 [#output-8]

  | 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 |
</ReferenceDetails>

### Get Phone Number Messages [#get-phone-number-messages]

Fetch messages received on a specific phone number

<ReferenceDetails>
  #### Input [#input-9]

  | 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 [#output-9]

  | 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 |
</ReferenceDetails>

### Get Usage [#get-usage]

Retrieve current usage statistics for the AgentPhone account

<ReferenceDetails>
  #### Input [#input-10]

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

  #### Output [#output-10]

  | 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 |
</ReferenceDetails>

### Get Daily Usage [#get-daily-usage]

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

<ReferenceDetails>
  #### Input [#input-11]

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

  #### Output [#output-11]

  | 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 |
</ReferenceDetails>

### Get Monthly Usage [#get-monthly-usage]

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

<ReferenceDetails>
  #### Input [#input-12]

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

  #### Output [#output-12]

  | 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 |
</ReferenceDetails>

### List Calls [#list-calls]

List voice calls for this AgentPhone account

<ReferenceDetails>
  #### Input [#input-13]

  | 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 [#output-13]

  | 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 |
</ReferenceDetails>

### List Contacts [#list-contacts]

List contacts for this AgentPhone account

<ReferenceDetails>
  #### Input [#input-14]

  | 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 [#output-14]

  | 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 |
</ReferenceDetails>

### List Conversations [#list-conversations]

List conversations (message threads) for this AgentPhone account

<ReferenceDetails>
  #### Input [#input-15]

  | 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 [#output-15]

  | 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 |
</ReferenceDetails>

### List Phone Numbers [#list-phone-numbers]

List all phone numbers provisioned for this AgentPhone account

<ReferenceDetails>
  #### Input [#input-16]

  | 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 [#output-16]

  | 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 |
</ReferenceDetails>

### React to Message [#react-to-message]

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

<ReferenceDetails>
  #### Input [#input-17]

  | 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 [#output-17]

  | 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) |
</ReferenceDetails>

### Release Phone Number [#release-phone-number]

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

<ReferenceDetails>
  #### Input [#input-18]

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

  #### Output [#output-18]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | ID of the released phone number |
  | `released` | boolean | Whether the number was released successfully |
</ReferenceDetails>

### Send Message [#send-message]

Send an outbound SMS or iMessage from an AgentPhone agent

<ReferenceDetails>
  #### Input [#input-19]

  | 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 [#output-19]

  | 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 |
</ReferenceDetails>

### Update Contact [#update-contact]

Update a contact's fields

<ReferenceDetails>
  #### Input [#input-20]

  | 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 [#output-20]

  | 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 |
</ReferenceDetails>

### Update Conversation [#update-conversation]

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

<ReferenceDetails>
  #### Input [#input-21]

  | 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 [#output-21]

  | 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 |
</ReferenceDetails>