AgentPhone

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.

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.

Actions

agentphone_create_call

Initiate an outbound voice call from an AgentPhone agent

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
agentIdstringYesAgent that will handle the call
toNumberstringYesPhone number to call in E.164 format (e.g. +14155551234)
fromNumberIdstringNoPhone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used.
initialGreetingstringNoOptional greeting spoken when the recipient answers
voicestringNoVoice ID override for this call (defaults to the agent's configured voice)
systemPromptstringNoWhen provided, uses a built-in LLM for the conversation instead of forwarding to your webhook

Output

ParameterTypeDescription
idstringUnique call identifier
agentIdstringAgent handling the call
statusstringInitial call status
toNumberstringDestination phone number
fromNumberstringCaller ID used for the call
phoneNumberIdstringID of the phone number used as caller ID
directionstringCall direction (outbound)
startedAtstringISO 8601 timestamp

agentphone_create_contact

Create a new contact in AgentPhone

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
phoneNumberstringYesPhone number in E.164 format (e.g. +14155551234)
namestringYesContact's full name
emailstringNoContact's email address
notesstringNoFreeform notes stored on the contact

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_create_number

Provision a new SMS- and voice-enabled phone number

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
countrystringNoTwo-letter country code (e.g. US, CA). Defaults to US.
areaCodestringNoPreferred area code (US/CA only, e.g. "415"). Best-effort — may be ignored if unavailable.
agentIdstringNoOptionally attach the number to an agent immediately

Output

ParameterTypeDescription
idstringUnique phone number ID
phoneNumberstringProvisioned phone number in E.164 format
countrystringTwo-letter country code
statusstringNumber status (e.g. active)
typestringNumber type (e.g. sms)
agentIdstringAgent the number is attached to
createdAtstringISO 8601 timestamp when the number was created

agentphone_delete_contact

Delete a contact by ID

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID

Output

ParameterTypeDescription
idstringID of the deleted contact
deletedbooleanWhether the contact was deleted successfully

agentphone_get_call

Fetch a call and its full transcript

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
callIdstringYesID of the call to retrieve

Output

ParameterTypeDescription
idstringCall ID
agentIdstringAgent that handled the call
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number used for the call
fromNumberstringCaller phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
statusstringCall status
startedAtstringISO 8601 timestamp
endedAtstringISO 8601 timestamp
durationSecondsnumberCall duration in seconds
lastTranscriptSnippetstringLast transcript snippet
recordingUrlstringRecording audio URL
recordingAvailablebooleanWhether a recording is available
transcriptsarrayOrdered transcript turns for the call
idstringTranscript turn ID
transcriptstringUser utterance
confidencenumberSpeech recognition confidence
responsestringAgent response (when available)
createdAtstringISO 8601 timestamp

agentphone_get_call_transcript

Get the full ordered transcript for a call

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
callIdstringYesID of the call to retrieve the transcript for

Output

ParameterTypeDescription
callIdstringCall ID
transcriptarrayOrdered transcript turns for the call
rolestringSpeaker role (user or agent)
contentstringTurn content
createdAtstringISO 8601 timestamp

agentphone_get_contact

Fetch a single contact by ID

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_get_conversation

Get a conversation along with its recent messages

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
messageLimitnumberNoNumber of recent messages to include (default 50, max 100)

Output

ParameterTypeDescription
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
messageCountnumberNumber of messages in the conversation
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
messagesarrayRecent messages in the conversation
idstringMessage ID
bodystringMessage text
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringsms, mms, or imessage
mediaUrlstringAttached media URL
mediaUrlsarrayAll attached media URLs
receivedAtstringISO 8601 timestamp

agentphone_get_conversation_messages

Get paginated messages for a conversation

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
limitnumberNoNumber of messages to return (default 50, max 200)
beforestringNoReturn messages received before this ISO 8601 timestamp
afterstringNoReturn messages received after this ISO 8601 timestamp

Output

ParameterTypeDescription
dataarrayMessages in the conversation
idstringMessage ID
bodystringMessage text
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringsms, mms, or imessage
mediaUrlstringAttached media URL
mediaUrlsarrayAll attached media URLs
receivedAtstringISO 8601 timestamp
hasMorebooleanWhether more messages are available

agentphone_get_number_messages

Fetch messages received on a specific phone number

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
numberIdstringYesID of the phone number
limitnumberNoNumber of messages to return (default 50, max 200)
beforestringNoReturn messages received before this ISO 8601 timestamp
afterstringNoReturn messages received after this ISO 8601 timestamp

Output

ParameterTypeDescription
dataarrayMessages received on the number
idstringMessage ID
from_stringSender phone number (E.164)
tostringRecipient phone number (E.164)
bodystringMessage text
directionstringinbound or outbound
channelstringChannel (sms, mms, etc.)
receivedAtstringISO 8601 timestamp
hasMorebooleanWhether more messages are available

agentphone_get_usage

Retrieve current usage statistics for the AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key

Output

ParameterTypeDescription
planjsonPlan name and limits (name, limits: numbers/messagesPerMonth/voiceMinutesPerMonth/maxCallDurationMinutes/concurrentCalls)
numbersjsonPhone number usage (used, limit, remaining)
statsjsonUsage stats: totalMessages, messagesLast24h/7d/30d, totalCalls, callsLast24h/7d/30d, totalWebhookDeliveries, successfulWebhookDeliveries, failedWebhookDeliveries
periodStartstringBilling period start
periodEndstringBilling period end

agentphone_get_usage_daily

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

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
daysnumberNoNumber of days to return (1-365, default 30)

Output

ParameterTypeDescription
dataarrayDaily usage entries
datestringDay (YYYY-MM-DD)
messagesnumberMessages that day
callsnumberCalls that day
webhooksnumberWebhook deliveries that day
daysnumberNumber of days returned

agentphone_get_usage_monthly

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

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
monthsnumberNoNumber of months to return (1-24, default 6)

Output

ParameterTypeDescription
dataarrayMonthly usage entries
monthstringMonth (YYYY-MM)
messagesnumberMessages that month
callsnumberCalls that month
webhooksnumberWebhook deliveries that month
monthsnumberNumber of months returned

agentphone_list_calls

List voice calls for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)
statusstringNoFilter by status (completed, in-progress, failed)
directionstringNoFilter by direction (inbound, outbound)
typestringNoFilter by call type (pstn, web)
searchstringNoSearch by phone number (matches fromNumber or toNumber)

Output

ParameterTypeDescription
dataarrayCalls
idstringCall ID
agentIdstringAgent that handled the call
phoneNumberIdstringPhone number ID used for the call
phoneNumberstringPhone number used for the call
fromNumberstringCaller phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
statusstringCall status
startedAtstringISO 8601 timestamp
endedAtstringISO 8601 timestamp
durationSecondsnumberCall duration in seconds
lastTranscriptSnippetstringLast transcript snippet
recordingUrlstringRecording audio URL
recordingAvailablebooleanWhether a recording is available
hasMorebooleanWhether more results are available
totalnumberTotal number of matching calls

agentphone_list_contacts

List contacts for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
searchstringNoFilter by name or phone number (case-insensitive contains)
limitnumberNoNumber of results to return (default 50, max 200)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayContacts
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of contacts

agentphone_list_conversations

List conversations (message threads) for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayConversations
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
lastMessagePreviewstringLast message preview
messageCountnumberNumber of messages in the conversation
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of conversations

agentphone_list_numbers

List all phone numbers provisioned for this AgentPhone account

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
limitnumberNoNumber of results to return (default 20, max 100)
offsetnumberNoNumber of results to skip (min 0)

Output

ParameterTypeDescription
dataarrayPhone numbers
idstringPhone number ID
phoneNumberstringPhone number in E.164 format
countrystringTwo-letter country code
statusstringNumber status
typestringNumber type (e.g. sms)
agentIdstringAttached agent ID
createdAtstringISO 8601 creation timestamp
hasMorebooleanWhether more results are available
totalnumberTotal number of phone numbers

agentphone_react_to_message

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

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
messageIdstringYesID of the message to react to
reactionstringYesReaction type: love, like, dislike, laugh, emphasize, or question

Output

ParameterTypeDescription
idstringReaction ID
reactionTypestringReaction type applied
messageIdstringID of the message that was reacted to
channelstringChannel (imessage)

agentphone_release_number

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

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
numberIdstringYesID of the phone number to release

Output

ParameterTypeDescription
idstringID of the released phone number
releasedbooleanWhether the number was released successfully

agentphone_send_message

Send an outbound SMS or iMessage from an AgentPhone agent

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
agentIdstringYesAgent sending the message
toNumberstringYesRecipient phone number in E.164 format (e.g. +14155551234)
bodystringYesMessage text to send
mediaUrlstringNoOptional URL of an image, video, or file to attach
numberIdstringNoPhone number ID to send from. If omitted, the agent's first assigned number is used.

Output

ParameterTypeDescription
idstringMessage ID
statusstringDelivery status
channelstringsms, mms, or imessage
fromNumberstringSender phone number
toNumberstringRecipient phone number

agentphone_update_contact

Update a contact's fields

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
contactIdstringYesContact ID
phoneNumberstringNoNew phone number in E.164 format
namestringNoNew contact name
emailstringNoNew email address
notesstringNoNew freeform notes

Output

ParameterTypeDescription
idstringContact ID
phoneNumberstringPhone number in E.164 format
namestringContact name
emailstringContact email address
notesstringFreeform notes
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp

agentphone_update_conversation

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

Input

ParameterTypeRequiredDescription
apiKeystringYesAgentPhone API key
conversationIdstringYesConversation ID
metadatajsonNoCustom key-value metadata to store on the conversation. Pass null to clear existing metadata.

Output

ParameterTypeDescription
idstringConversation ID
agentIdstringAgent ID
phoneNumberIdstringPhone number ID
phoneNumberstringPhone number
participantstringExternal participant phone number
lastMessageAtstringISO 8601 timestamp
messageCountnumberNumber of messages
metadatajsonCustom metadata stored on the conversation
createdAtstringISO 8601 timestamp
messagesarrayMessages in the conversation
idstringMessage ID
bodystringMessage body
fromNumberstringSender phone number
toNumberstringRecipient phone number
directionstringinbound or outbound
channelstringChannel (sms, mms, etc.)
mediaUrlstringMedia URL if any
mediaUrlsarrayAll attached media URLs
receivedAtstringISO 8601 timestamp

On this page