Skip to main content
Go from zero to a working voice agent you can call from your phone. By the end, you’ll have a LiveKit agent deployed on Telnyx infrastructure, connected to a real phone number.

​
Prerequisites

Before you start, make sure you have:
  • A Telnyx account
  • A Telnyx API key (generate one in the portal)
  • A secret key you create and keep safe — this is your LIVEKIT_API_SECRET
  • Python ≥ 3.10
  • LiveKit CLI (lk) version 2.16.0 or later
Verify your CLI version: 
lk version

​
Step 1: Configure the CLI

Set your environment variables to point at a Telnyx LiveKit region: 
export TELNYX_API_KEY=<your-telnyx-api-key>
export LIVEKIT_URL=https://<region>.livekit-telnyx.com
export LIVEKIT_API_KEY=$TELNYX_API_KEY
export LIVEKIT_API_SECRET=<your-secret>
LIVEKIT_API_KEY is your Telnyx API key — the same one you use everywhere else on the platform. Set TELNYX_API_KEY once and reference it throughout.

​
Available regions

RegionName (slug)URL
New Yorknyc1nyc1.livekit-telnyx.com
San Franciscosfo3sfo3.livekit-telnyx.com
Atlantaatl1atl1.livekit-telnyx.com
Sydneysyd1syd1.livekit-telnyx.com
Choose the region closest to your users for the lowest latency.

​
Step 2: Set up telephony

To receive phone calls, you need a phone number (DID) pointed at the Telnyx LiveKit SIP servers. No third-party SIP fees — Telnyx is the carrier.

​
Buy a phone number

Search for an available number in your area code and order it:1. Browse available numbers (replace 512 with your area code):
curl -sg "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[national_destination_code]=512" \
  -H "Authorization: Bearer $TELNYX_API_KEY" | \
  jq -r '["NUMBER","LOCATION","MONTHLY"], (.data[] | [.phone_number, (.region_information | map(.region_name) | join(", ")), .cost_information.monthly_cost]) | @tsv' | \
  column -t | less
Note the number you want before exiting — you’ll need it below.
2. Order the number you want:
curl -s -X POST "https://api.telnyx.com/v2/number_orders" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_numbers": [{"phone_number": "+1XXXXXXXXXX"}]}' | \
  jq '{id: .data.id, status: .data.status, phone_number: .data.phone_numbers[0].phone_number}'
3. Confirm the order completed:
curl -s "https://api.telnyx.com/v2/number_orders/ORDER_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" | \
  jq '{id: .data.id, status: .data.status, phone_number: .data.phone_numbers[0].phone_number}'
Wait for "success" before moving on.
If your order didn’t complete successfully, chat with us — we’re happy to help.

​
Create a SIP connection

A SIP connection tells Telnyx how to route inbound calls. You’ll point it at one of our regional LiveKit SIP servers so calls land on the right infrastructure.
RegionName (slug)SIP FQDN
New Yorknyc1nyc1.sip.livekit-telnyx.com
San Franciscosfo3sfo3.sip.livekit-telnyx.com
Atlantaatl1atl1.sip.livekit-telnyx.com
Sydneysyd1syd1.sip.livekit-telnyx.com
1. Create the FQDN connection (replace {slug} with your region slug):
curl -s -X POST "https://api.telnyx.com/v2/fqdn_connections" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_name": "{slug}-livekit-sip-connection"}' | \
  jq '{id: .data.id, name: .data.connection_name}'
2. Attach the regional SIP FQDN (replace CONNECTION_ID and {slug} with your region slug):
curl -s -X POST "https://api.telnyx.com/v2/fqdns" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_id": "CONNECTION_ID", "fqdn": "{slug}.sip.livekit-telnyx.com", "dns_record_type": "a", "port": 5060}' | \
  jq '{fqdn: .data.fqdn, connection_id: .data.connection_id}'
3. Assign your phone number to the connection (replace CONNECTION_ID and phone number):
curl -s -X PATCH "https://api.telnyx.com/v2/phone_numbers/+1XXXXXXXXXX" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_id": "CONNECTION_ID"}' | \
  jq '{phone_number: .data.phone_number, connection_id: .data.connection_id}'

​
Register the number with the platform

Set up an inbound trunk for your number and a dispatch rule to route calls to your agent. 1. Create an inbound SIP trunk: 
echo '{
  "trunk": {
    "name": "telnyx-inbound",
    "numbers": ["+1XXXXXXXXXX"],
    "allowed_addresses": ["192.76.120.0/22"]
  }
}' | lk sip inbound create -
Note the trunk sid in the response — you’ll need it in the next step.
allowed_addresses restricts which source IPs can send SIP traffic to this trunk. 192.76.120.0/22 is Telnyx’s SIP network — since Telnyx is your carrier, all inbound calls will originate from this range.
2. Create a dispatch rule: 
echo '{
  "dispatchRule": {
    "name": "route-to-agent",
    "trunkIds": ["<TRUNK_ID>"],
    "rule": { "dispatchRuleIndividual": {} },
    "roomConfig": { "agents": [{ "agentName": "agent" }] }
  }
}' | lk sip dispatch create -

​
Step 3: Clone an example agent

Clone the example agents repo and navigate to the restaurant agent: 
git clone https://github.com/team-telnyx/telnyx-livekit-agent-examples.git
cd telnyx-livekit-agent-examples/restaurant
This is a fully working voice agent — an Italian restaurant ordering assistant built with livekit-plugins-telnyx for STT, TTS, and LLM.

​
Step 4: Deploy

Deploy the agent to your Telnyx LiveKit region: 
lk agent deploy . --url $LIVEKIT_URL
The CLI uploads your agent code, builds a container image, and deploys it. You’ll see build logs streaming in real-time. Check that your agent is running: 
lk agent status

​
Step 5: Call your agent

Pick up your phone and dial the number you purchased. You should hear:
“Thanks for calling Bella’s Kitchen!”
Try ordering some pasta. The agent handles the full conversation — browsing the menu, answering questions, and taking your order.

​
Troubleshooting

  • Call doesn’t connect — Verify your SIP connection is pointed at the correct regional FQDN and your DID is assigned to it.
  • Agent doesn’t pick up — Run lk agent status to confirm the agent is running. Check logs with lk agent logs.
  • Audio quality issues — Make sure you’re using the region closest to you.

​
Next steps

You’ve deployed your first agent. Here’s where to go from here:
  • Build — Write your own agent from scratch
  • Deploy — Regions, scaling, secrets, and production deployment
  • Models — STT, TTS, and LLM options available on Telnyx
  • Telephony — Inbound/outbound calls, dispatch rules, multiple numbers
  • Compatibility — What’s the same and different from LiveKit Cloud