> ## Documentation Index
> Fetch the complete documentation index at: https://nenyax.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Telephony

> Inbound and outbound phone calls via Twilio with auto-provisioned SIP infrastructure.

# Telephony

Nenyax 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

```bash theme={null}
# 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 `nenyax-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

```bash theme={null}
# 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

* A [Twilio account](https://www.twilio.com/try-twilio) with Account SID and Auth Token
* A [LiveKit Cloud account](https://cloud.livekit.io) with API Key, API Secret, and Server URL
* Both configured via **API Keys** in the dashboard

Everything else (SIP trunks, dispatch rules, credentials) is auto-provisioned.

See [Telephony Setup](/configuration/telephony) for the full configuration guide.