Skip to main content

​
Telephony

Arkenos supports real phone calls through Twilio and LiveKit SIP. The SIP infrastructure (trunks, dispatch rules, credentials) is auto-provisioned — you just need Twilio and LiveKit account credentials.

​
Phone Number Management

Manage phone numbers directly from the dashboard or API:
  • Search: Find available numbers by area code or country
  • Buy: Purchase a number — automatically provisions all SIP infrastructure and assigns to an agent
  • Assign: Assign an already-owned Twilio number to an agent (also auto-provisions)
  • Release: Unassign a number from an agent — removes SIP routing but keeps the number in your Twilio account
  • Retry: Re-run provisioning if it partially failed during buy/assign
# Search available numbers
curl "http://localhost:8000/api/telephony/numbers/search?country=US&area_code=510"

# Buy and assign to agent (auto-provisions everything)
curl -X POST http://localhost:8000/api/telephony/numbers/buy \
  -H "Content-Type: application/json" \
  -H "x-user-id: your-user-id" \
  -d '{"phone_number": "+15105550100", "agent_id": "uuid"}'

# Release a number
curl -X POST http://localhost:8000/api/telephony/numbers/release \
  -H "Content-Type: application/json" \
  -H "x-user-id: your-user-id" \
  -d '{"agent_id": "uuid"}'

​
Inbound Calls

When someone calls a number assigned to an agent:
  1. Twilio routes the call to LiveKit via the auto-provisioned Elastic SIP Trunk
  2. LiveKit’s dispatch rule creates a room and dispatches arkenos-agent
  3. The agent calls /api/telephony/lookup to resolve the phone number to the correct agent config
  4. The agent loads the matching system prompt, voice, greeting, and tools

​
Outbound Calls

Initiate calls from the dashboard or API:
  1. Select an agent and enter a phone number in the dashboard (or call POST /api/calls/outbound)
  2. The backend auto-provisions an outbound SIP trunk (first call only)
  3. LiveKit creates a room, dials the number through Twilio, and dispatches the agent
  4. The agent joins and handles the conversation
# Initiate an outbound call
curl -X POST http://localhost:8000/api/calls/outbound \
  -H "Content-Type: application/json" \
  -H "x-user-id: your-user-id" \
  -d '{"agent_id": "uuid", "phone_number": "+15105550100"}'

​
Prerequisites

Everything else (SIP trunks, dispatch rules, credentials) is auto-provisioned. See Telephony Setup for the full configuration guide.