AI voice agents

An AI voice agent is a forward destination like any other. Point a number at it and the agent answers every inbound call. Pass it as forwardTo on one outbound call and the agent talks to whoever picks up. Pozy owns the phone side: the number, the carrier leg, routing, recording and the call history. The agent owns the conversation.

#Pick a shape

Either way there is no second phone leg, so you pay only for the call itself.

#Point a number at the agent

curl -X POST https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "forwardTo": "wss://agent.acme.example.com/media", "transcriptionEnabled": true }'

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ forwardTo: "wss://agent.acme.example.com/media", transcriptionEnabled: true }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.pstnForwardTo);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"forwardTo": "wss://agent.acme.example.com/media", "transcriptionEnabled": True},
    timeout=30,
)
print(resp.json()["pstnForwardTo"])

A hosted agent works the same way with a sip: address in forwardTo. Many hosted platforms identify the number from the SIP user part: keep the number in E.164 with the leading +, written the same way on both sides. A + missing on one side is the usual reason a call connects and drops at once.

The agent sits inside the normal inbound flow, so the blocklist, business hours, an IVR option that sends one digit to the agent, and voicemail all still apply. See Voice calls.

#Hand one outbound call to an agent

Pass the agent as the per-call destination. The number's inbound setting stays as it is.

curl -X POST https://api.pozy.ai/v1/voice/calls \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: reminder-appt-7781" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155550142",
    "to": "+13125550188",
    "forwardTo": "wss://agent.acme.example.com/media",
    "amd": true,
    "voicemailDropMessage": "Hi, this is Acme confirming your appointment tomorrow at 10. Call us back if you need to change it."
  }'

With amd: true, the agent is only bridged in when a person answers. An answering machine gets the voicemailDropMessage instead.

#Build your own agent over WebSocket

When the destination is wss://, the call's audio streams to your server as soon as the call is answered, and audio you send back is played to the caller. Pozy does not re-encode the audio.

These settings are fixed today, so build the pipeline around 8 kHz PCMU.

A typical loop:

1. Accept the WebSocket and wait for start.
2. Feed media payloads to speech-to-text.
3. Send each finished user turn to your LLM with the system prompt and tools.
4. Turn the reply into speech, encode it as PCMU at 8 kHz, and write it back as media frames.
5. On stop, or when the conversation is done, close the socket.

#Give the agent tools

Your agent's backend holds the Pozy API key, so Pozy endpoints make good agent tools. Match the call to its Pozy id with the call.received webhook, which fires as an inbound call starts and carries call.id, from, to and conversationId. For outbound calls, keep the callId from the create response.

#Capture the conversation

Turn on recordingEnabled and transcriptionEnabled on the number when you want Pozy to keep its own copy of the call. The recording and transcript attach to the call record after hangup. See Call recordings.

#When it does not connect

If the stream cannot be set up, an already-answered caller falls to voicemail when it is on. Otherwise the call ends.

#Endpoints

#Webhook events