Voice

AgentOwl v1 connects incoming calls to your SIP phone system or voice agent. AgentOwl owns the number configuration, funded admission, transfer command, call deadlines and usage settlement. Telnyx carries the call and transfers its media to your SIP service. Your service handles the conversation; AgentOwl does not need to host a voice runtime for this path.

Set up voice in Admin: check number availability and call limits, then configure your selected workspace's incoming-call destination and publish its route. Your account shows which setup actions are available. If setup is unavailable for your account, contact support@agentowl.dev with your workspace and the step that is blocked. Supported lifecycle callbacks use the shared event envelope; an event webhook is separate from call audio.

Get a voice number

Phone numbers require an active paid plan. Check number availability in Admin, then configure the incoming-call destination for your selected workspace. Check Pro purchase availability if your account needs a paid plan; viewing availability does not charge you. If number setup or purchase is unavailable for your account, contact support@agentowl.dev. In Admin, Voice & phone links to account-wide number setup and call limits, plus the selected workspace's route and Inbox.

On a paid workspace, include the voice capability when you connect the number:

agentowl messaging bind acme --capability voice

Or add it to an existing number:

agentowl messaging update <binding_id> --capability voice

Choose how calls are handled

How a call is handled depends on the type of endpoint that the number's route points to.

The v1 SIP path has real transfer, two-way media, signed completion and exactly-once billing evidence. Your voice service determines speech and conversation quality. Direct streaming and AgentOwl-hosted conversation are separate offerings; creating an endpoint does not activate them.

Voicemail

This is the default. AgentOwl answers, plays a greeting, and records a message:

1. The call is answered.
2. A greeting plays: "You've reached Organization name. Please leave a message after the beep."
3. After the beep, the caller's message is recorded as MP3 for up to 2 minutes, or until 5 seconds of silence.
4. The recording is saved and an event with its URL is delivered.

To change the greeting, create a voice-config policy with greeting_text, attach it to the number, and publish. See Policies.

Recordings are listed in the dashboard Inbox under Call recordings, with a player. A number marked assigned does not prove that its voice route or recording delivery is working; place a test call and check for the saved recording.

Voice agent

In the preview path, route the number to a voice-runtime endpoint to connect callers to your own voice agent. AgentOwl answers the call and opens a bidirectional media stream to your runtime. No greeting is played. Recording requires a separate funded, notice-reviewed setup and is not implied by creating this endpoint; your agent handles the conversation.

agentowl endpoint create --type voice-runtime --name support-agent \
  --runtime-url wss://voice.example.com \
  --stream-token-secret-ref acme/voice-stream-token \
  --tenant acme

• The stream connects to <runtime-url><stream-path>?stream_auth_token=<token>. The default path is /ws/telnyx/{call_id}. Check the token at the WebSocket handshake.
• Audio is sent in both directions as L16 PCM at 16 kHz.
• The runtime URL must use TLS (wss:// or https://).
• The stream token is read from a stored secret (--stream-token-secret-ref). Email and SMS routed to a voice-runtime endpoint aren't delivered.

SIP transfer

Check voice setup availability for your account and confirm an active paid entitlement, then create a SIP endpoint for the destination you control:

agentowl endpoint create sip support-phone --tenant acme \
  --config '{"sip_uri":"sips:agent@voice.example.com:5061"}'

A sip: URI uses the configured SIP destination; a sips: URI requests TLS transport. AgentOwl preserves your configured URI and sends the carrier its supported SIP URI plus explicit TLS transport. Bind your active number to this endpoint, publish the workspace's route and check your account's funded call limits before activation. A saved endpoint alone does not make the number live.

Call the assigned number after activation. Confirm that your receiver answers, media flows in both directions, and both call legs end. Inspect call events and Voice usage in the same account. SIP transfer does not start AgentOwl greeting, recording, transcription, streaming or model usage. Your destination may supply its own services under its own terms.

SIP charges and unused reservations

The saved accepted quote covers the inbound leg, outbound leg and transfer invocation. Customer call-leg usage uses the measured call duration at the accepted prices. Carrier billing minima and later provider invoices are separate company costs; they do not rewrite a fixed customer price.

A reservation is a spending limit, not the final charge. Normal settlement charges accepted measured usage once and releases the remainder. If usage is still unknown after both signed call-leg endings, the financial closeout runs 24 hours after the later saved call deadline or last signed terminal receipt. It charges accepted measurements within the quote, releases the unused hold and retains unknown components for investigation with no automatic customer charge. Historical calls without the required signed endings and contradictory call identities remain under review. Late evidence is reviewed without automatically rebilling a closed reservation.

Need help? Send support the workspace, approximate call time and event ID. Never send an API key, SIP password or private recording link.

Event payload

Voice events have channel: "voice" and provider: "telnyx". Supported provider callbacks become events, and provider_event_type names the step. Callback coverage depends on the selected route; do not assume the webhook is an audio stream:

Events for one call share subject.call_session_id. They can arrive out of order, so use occurred_at to order them.

{
  "channel": "voice",
  "provider": "telnyx",
  "provider_event_type": "call.recording.saved",
  "subject": {
    "from": "+12125550183",
    "to": "+12125550142",
    "phone_number": "+12125550183",
    "call_session_id": "4d5e..."
  },
  "payload": {
    "inline": {
      "call_control_id": "v3:...",
      "call_session_id": "4d5e...",
      "direction": "incoming",
      "recording_id": "a1b2...",
      "recording_url": "https://...mp3",
      "recording_duration_secs": 12,
      "hangup_cause": null
    }
  }
}

Later events in a call may not repeat from and to. Keep them from call.initiated.

Recording links

The recording_url in the event expires about 10 minutes after the recording is saved. Download the recording right away. If the link has expired, fetch the event again for a fresh link:

curl -H "Authorization: Bearer $AGENTOWL_API_TOKEN" \
  https://api.agentowl.dev/v1/events/evt_...

AgentOwl doesn't keep its own copy of recordings. They're stored by the carrier.

Check setup and recover a missing call

1. In Admin, open Voice & phone → Check number setup. Confirm the number is assigned and in service. A setup job may instead be waiting for number selection, retry, or operator review. Plan access and number setup are separate states.
2. For the selected workspace, open Check the voice route. Confirm that an active voice binding points to a published voicemail route. For v1 SIP transfers, check the published SIP endpoint and your receiver instead; direct voice-runtime streaming remains preview.
3. Place a test call. For SIP, confirm your destination answers, media flows both ways, and both legs end; inspect call events and Voice usage in the same account. For a separately configured voicemail route, open Call recordings in the workspace Inbox. A recording callback may arrive after hangup.
4. If a recording player reports an expired or inaccessible link, use Renew recording link in the event detail. The server requests a fresh provider link only after checking workspace access and matching the saved call identity. If the carrier cannot renew it, the event remains visible and you can retry later.
5. Check Call limits for the server-reported enforcement state and Voice usage for rated or pending usage. A saved limit may not yet be enforced, and final usage may arrive after the call ends.

If the call is still missing or a paid charge remains under review, contact support@agentowl.dev with the workspace, number, approximate time, and event ID if available. Do not send API keys, stream tokens, or private recording links. For voice setup, open Voice & phone in Admin; direct streaming, AgentOwl-hosted conversation and customer-initiated outgoing calls have separate availability.

Reviewing an outgoing call request

Public outgoing calling remains gated. In Voice & phone → Review outgoing calls and limits, check availability for the workspace. When calling is permitted, choose an approved caller number, destination and voice connection, then enter the requested maximum duration and reservation budget. Reserve and review call reserves funds; it does not dial. Confirm the server-verified reservation separately to start the recorded call.

A saved browser request is only a recovery handle. After an interrupted preparation, Retry same preparation reuses that request. After an uncertain start, use Check call status and outgoing history; the screen never automatically redials. Unsent requests can be canceled only when the server confirms they remain cancelable. Final usage may arrive after termination, and a reservation is not a final charge.