AgentPhone é uma plataforma de voz e mensagens API-first construída para agentes de IA. O AgentPhone permite que você provisione números de telefone reais, faça chamadas de voz de saída de IA, envie SMS e iMessage, gerencie conversas e contatos e monitore o uso — tudo por meio de uma API REST simples projetada para acesso programático.
Por que AgentPhone?
- Telefonia nativa para agentes: Projetado especificamente para agentes de IA — provisione números, faça chamadas e envie mensagens sem contratos de operadora ou encanamento de telefonia.
- Voz + Mensagens na mesma API: Impulsione chamadas de voz de IA de saída junto com SMS, MMS e iMessage da mesma conta e números de telefone.
- Gerenciamento de conversas e transcrições: Cada chamada retorna uma transcrição ordenada; cada thread de mensagem é rastreada como uma conversa com histórico completo e metadados.
- Contatos embutidos: Crie, pesquise, atualize e exclua contatos na conta para que seus agentes possam referenciar pessoas pelo nome em vez de números de telefone brutos.
- Visibilidade do uso: Inspecione os limites do plano, os contagens atuais e as agregações diárias/mensais para que os fluxos de trabalho permaneçam dentro das restrições.
Usando AgentPhone em Zoen
A integração do AgentPhone com Zoen conecta seus fluxos de trabalho de agentes diretamente ao AgentPhone usando uma chave de API. Com 22 operações que abrangem números, chamadas, conversas, contatos e uso, você pode construir automações de voz e mensagens poderosas sem escrever código de backend.
Principais benefícios de usar o AgentPhone em Zoen:
- Provisionamento dinâmico de números: Reserve números nos EUA ou Canadá sob demanda — por agente, por cliente ou por fluxo de trabalho — e libere-os quando não forem mais necessários.
- Chamadas de voz de IA de saída: Faça chamadas de um agente com uma saudação opcional, sobreposição de voz ou prompt do sistema e leia o transcript completo como dados estruturados uma vez que a chamada seja concluída.
- Mensagens de duas vias: Envie SMS, MMS ou iMessage, recupere o histórico de conversas e reaja a iMessages recebidos — tudo dentro do seu fluxo de trabalho.
- Gerenciamento de contatos e metadados: Mantenha uma lista de contatos de nível de conta e anexe metadados JSON personalizados às conversas para que blocos subsequentes possam ramificar com base no estado.
- Visão operacional: Extraia estatísticas de uso atuais e divisões diárias/mensais para monitorar o consumo e impor limites de plano antes de fazer a próxima chamada.
Se você estiver construindo um agente de voz de IA de saída, executando acompanhamentos de SMS automatizados, gerenciando conversas de clientes de duas vias ou monitorando o uso do telefone em toda a sua organização, o AgentPhone em Zoen fornece acesso direto e seguro à API completa do AgentPhone — sem middleware necessário. Basta configurar sua chave de API, selecionar a operação necessária e deixe o Zoen fazer o resto.
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.
Initiate an outbound voice call from an AgentPhone agent
| 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 |
| 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 a new contact in AgentPhone
| 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 |
| 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 |
Provision a new SMS- and voice-enabled phone number
| 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 |
| 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 a contact by ID
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
contactId | string | Yes | Contact ID |
| Parameter | Type | Description |
|---|
id | string | ID of the deleted contact |
deleted | boolean | Whether the contact was deleted successfully |
Fetch a call and its full transcript
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
callId | string | Yes | ID of the call to retrieve |
| 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 the full ordered transcript for a call
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
callId | string | Yes | ID of the call to retrieve the transcript for |
| 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 |
Fetch a single contact by ID
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
contactId | string | Yes | Contact ID |
| 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 a conversation along with its recent messages
| 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) |
| 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 paginated messages for a conversation
| 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 |
| 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 |
Fetch messages received on a specific phone number
| 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 |
| 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 |
Retrieve current usage statistics for the AgentPhone account
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
| 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 a daily breakdown of usage (messages, calls, webhooks) for the last N days
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
days | number | No | Number of days to return (1-365, default 30) |
| 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 aggregation (messages, calls, webhooks) for the last N months
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
months | number | No | Number of months to return (1-24, default 6) |
| 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 voice calls for this AgentPhone account
| 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) |
| 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 for this AgentPhone account
| 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) |
| 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 (message threads) for this AgentPhone account
| 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) |
| 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 all phone numbers provisioned for this AgentPhone account
| 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) |
| 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 |
Send an iMessage tapback reaction to a message (iMessage only)
| 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 |
| 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 (delete) a phone number. This action is irreversible.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | AgentPhone API key |
numberId | string | Yes | ID of the phone number to release |
| Parameter | Type | Description |
|---|
id | string | ID of the released phone number |
released | boolean | Whether the number was released successfully |
Send an outbound SMS or iMessage from an AgentPhone agent
| 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. |
| 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 a contact's fields
| 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 |
| 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 metadata (stored state). Pass null to clear existing metadata.
| 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. |
| 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 |