# Telnyx AI: LiveKit on Telnyx (Beta) — Full Documentation
> Complete page content for LiveKit on Telnyx (Beta) (AI section) of the Telnyx developer docs (https://developers.telnyx.com).
> Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/ai/livekit.txt

## LiveKit on Telnyx (Beta)

### Overview

> Source: https://developers.telnyx.com/docs/livekit.md

# LiveKit on Telnyx

Build, deploy, and scale voice AI agents on Telnyx's global network — the same LiveKit you know, hosted on Telnyx infrastructure with integrated telephony and AI models.

## Why LiveKit on Telnyx?

LiveKit on Telnyx collapses your voice AI stack into a single platform:

- **Built-in Telephony, No Third-Party SIP Fees** — Telnyx is the carrier. Buy numbers, configure SIP, connect to agents — all in one portal. On other platforms, you pay third-party SIP fees on top of your usage. On Telnyx, those are gone entirely.

- **Ultra-Low Latency AI on Telnyx GPUs** — STT, TTS, and LLM run on Telnyx-owned GPUs, colocated in every region ~2ms from your agents. No round-trips to external APIs — faster responses, better conversations.

- **Same LiveKit, Zero Migration Risk** — Same SDKs, same CLI, same agent framework. Swap three environment variables and redeploy — your code doesn't change.

- **One Platform, One Bill** — Compute, models, telephony, and phone numbers — all on a single Telnyx invoice. No vendor sprawl.

## Not ready to migrate?

Install the [Telnyx plugin](/docs/livekit/build#1-install-the-plugin) on your existing LiveKit Cloud or self-hosted setup. Same agent code, same infrastructure — just faster, colocated inference on Telnyx GPUs. See the [Plugin Reference](/docs/livekit/models) for available STT, TTS, and LLM options.

## Who is this for?

- **LiveKit Cloud users** looking to consolidate vendors or reduce latency via Telnyx's network
- **Self-hosted LiveKit operators** tired of managing infrastructure and wanting managed hosting
- **New voice AI developers** who want a single platform for media, telephony, and AI

## How it works

1. **Connect** — Configure your LiveKit client to point to Telnyx's LiveKit cluster using your Telnyx credentials.
2. **Build** — Write agents using the LiveKit Agent framework with Telnyx plugins for STT, TTS, and LLM.
3. **Deploy** — Deploy agents to Telnyx's managed infrastructure. Telephony connects via built-in SIP.
4. **Scale** — Telnyx handles the infrastructure. You manage your agents and configuration.

## What's different from LiveKit Cloud?

| Feature | LiveKit on Telnyx | LiveKit Cloud |
|---------|-------------------|---------------|
| SIP trunking | Built-in — no third-party SIP fees, HD voice (G.722 + Opus) | Third-party SIP fees on top of usage |
| AI models | Colocated on Telnyx GPUs (~2ms from agents) | LiveKit Inference or third-party APIs |
| Billing | Combined with Telnyx services | Separate |

## Next steps

- [Quickstart](/docs/livekit/quickstart) — Get deployed in 5 minutes
- [Connect](/docs/livekit/connect) — Configure your LiveKit client
- [Telephony](/docs/livekit/telephony) — SIP and PSTN integration
- [Plugin Reference](/docs/livekit/models) — STT, TTS, and LLM options

---

### Compatibility

> Source: https://developers.telnyx.com/docs/livekit/compatibility.md

## What's the Same

The LiveKit agent framework is 100% portable — your agent code does not change. Everything in LiveKit works identically on Telnyx. 

Notable sections from LiveKit docs:
- **Agent Framework** — [docs.livekit.io/agents](https://docs.livekit.io/agents)
- **SIP / Phone** — [docs.livekit.io/sip](https://docs.livekit.io/sip)
- **API Reference** — [docs.livekit.io/api](https://docs.livekit.io/api)
- **Cloud Deployment** — [docs.livekit.io/cloud](https://docs.livekit.io/cloud)
- **Egress / Ingress** — [docs.livekit.io/egress](https://docs.livekit.io/egress)

## What's Different

These features work differently on Telnyx compared to LiveKit Cloud:

- **STT / TTS / LLM** — LiveKit Cloud requires third-party AI providers. On Telnyx, hosted models are available out of the box via [`livekit-plugins-telnyx`](https://github.com/team-telnyx/telnyx-livekit-plugin). Prefer your own provider? Bring any API key.
- **SIP trunking** — On other platforms, you pay third-party SIP fees on top of your usage. On Telnyx, those are gone entirely — SIP is built-in because you're already on the carrier. BYOT also supported if you prefer your existing provider.
- **HD Voice** — G.722 (16 kHz) and Opus (48 kHz) codecs for wideband audio on SIP calls. G.722 is enabled by default. Opus requires SRTP — see [Telephony](/docs/livekit/telephony#hd-voice) for setup.
- **Phone numbers** — Telnyx numbers in 140+ countries instead of LiveKit Phone (US only)
- **Agent deployment** — Same `lk agent deploy` command. Just swap the URL: `lk agent deploy . --url .livekit.telnyx.com`

_Note: Available regions are nyc1, sfo3, atl1, and syd1. See the [Regions](/docs/livekit/regions) page for details._

## What's Not Supported

- **Ingress (RTMP/WHIP)** — importing external streams into a room
- **Sandbox** — quick-start dev environments

## Coming Soon

*This roadmap is subject to change.*

- **Egress** — Call recording, room recording, cloud storage export
- **Observability** — Cloud Dashboard with session timeline (transcripts, traces, logs, audio playback)
- **Agent Tooling** — Playground, Agent Builder
- **Security & Compliance** — E2E encryption, SSO, RBAC, HIPAA
- **Enterprise SIP** — Call transfers (REFER/warm transfer), and advanced SIP features
- **Media** — Enhanced noise cancellation (Krisp/BVC)

---

### Quick Start

> Source: https://developers.telnyx.com/docs/livekit/quickstart.md

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](https://portal.telnyx.com)
- A Telnyx API key (generate one in the [portal](https://portal.telnyx.com))
- A secret key you create and keep safe — this is your `LIVEKIT_API_SECRET`
- Python ≥ 3.10
- [LiveKit CLI](https://docs.livekit.io/home/cli/) (`lk`) version 2.16.0 or later

Verify your CLI version:

```bash
lk --version
```

## Step 1: Configure the CLI

Set your environment variables to point at a Telnyx LiveKit region:

```bash
export TELNYX_API_KEY=
export LIVEKIT_URL=https://.livekit-telnyx.com
export LIVEKIT_API_KEY=$TELNYX_API_KEY
export LIVEKIT_API_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.

Register your credentials with the platform:

```bash
curl -s -X POST "https://.livekit-telnyx.com/provision" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "api_key": "'$TELNYX_API_KEY'",
    "api_secret": "'$LIVEKIT_API_SECRET'"
  }'
```

This creates your tenant record on the platform. You only need to do this once per region.

### Available regions

| Region | Name (slug) | URL |
|--------|------|-----|
| New York | `nyc1` | `nyc1.livekit-telnyx.com` |
| San Francisco | `sfo3` | `sfo3.livekit-telnyx.com` |
| Atlanta | `atl1` | `atl1.livekit-telnyx.com` |
| Sydney | `syd1` | `syd1.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):

    ```bash
    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:**

    ```bash
    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:**

    ```bash
    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](https://telnyx.com/contact-us) — we're happy to help.
    
    1. Log in to the [Telnyx portal](https://portal.telnyx.com)
    2. Go to [**Real Time Communcations** → **Numbers** → **Buy Numbers**](https://portal.telnyx.com/#/numbers/buy-numbers)
    3. Purchase a number by checking out

### 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.

| Region | Name (slug) | SIP FQDN |
|--------|------|----------|
| New York | `nyc1` | `nyc1.sip.livekit-telnyx.com` |
| San Francisco | `sfo3` | `sfo3.sip.livekit-telnyx.com` |
| Atlanta | `atl1` | `atl1.sip.livekit-telnyx.com` |
| Sydney | `syd1` | `syd1.sip.livekit-telnyx.com` |

    **1. Create the FQDN connection** (replace `{slug}` with your region slug):

    ```bash
    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):

    ```bash
    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):

    ```bash
    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}'
    ```
    1. In the portal, go to [**Real Time Communcations** → **Voice** → **SIP Connections** → **Create**](https://portal.telnyx.com/#/voice/connections)
    2. Set the connection type to **FQDN**
    3. Point it at your region's SIP endpoint from the table above
    4. Assign your phone number to this SIP connection

### Register the number with the platform

Set up an [inbound trunk](https://docs.livekit.io/telephony/accepting-calls/inbound-trunk/) for your number and a [dispatch rule](https://docs.livekit.io/telephony/accepting-calls/dispatch-rule/) to route calls to your agent.

**1. Create an inbound SIP trunk:**

```bash
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:**

```bash
echo '{
  "dispatchRule": {
    "name": "route-to-agent",
    "trunkIds": [""],
    "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:

```bash
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`](https://github.com/team-telnyx/telnyx-livekit-plugin) for STT, TTS, and LLM.

## Step 4: Deploy

Register the agent with the platform, then deploy it to your Telnyx LiveKit region:

```bash
lk agent create .
lk agent deploy . --secrets TELNYX_API_KEY=$TELNYX_API_KEY
```

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:

```bash
lk agent status
```

`lk agent status` reads the agent ID from your `livekit.toml` file — you don't need to specify it manually. If you skip `lk agent create`, there's no ID in the file and the command will fail.

## 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](/docs/livekit/build) — Write your own agent from scratch
- [Deploy](/docs/livekit/deploy) — Regions, scaling, secrets, and production deployment
- [Models](/docs/livekit/models) — STT, TTS, and LLM options available on Telnyx
- [Telephony](/docs/livekit/telephony) — Inbound/outbound calls, dispatch rules, multiple numbers
- [Compatibility](/docs/livekit/compatibility) — What's the same and different from LiveKit Cloud

---

### Connect

> Source: https://developers.telnyx.com/docs/livekit/connect.md

Connecting to the Telnyx LiveKit platform is a URL and credential swap. No code changes.

## Get your credentials

Complete [Quickstart — Step 1](/docs/livekit/quickstart#step-1-configure-the-cli) to set your environment variables and register with the platform. That one-time setup covers everything you need to connect.

Already set up? Just make sure your `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` are exported in your shell.

Verify the connection:

```bash
lk room list
```

## Available regions

See [Regions](/docs/livekit/regions) for all available platform and SIP endpoints.

## SDK configuration

Server SDKs (Python, Go, Node.js) just need the URL and credentials:

```python
from livekit.api import LiveKitAPI

api = LiveKitAPI(
    url="https://nyc1.livekit-telnyx.com",
    api_key="",
    api_secret="",
)
```

If you're migrating from LiveKit Cloud or self-hosted, change the three environment variables and everything else stays the same.

---

## Migration

### From LiveKit Cloud

> Source: https://developers.telnyx.com/docs/livekit/migration/from-livekit-cloud.md

Zero code changes. Swap your credentials, redeploy, done.

## What changes

| | LiveKit Cloud | Telnyx |
|---|---|---|
| `LIVEKIT_URL` | `https://your-project.livekit.cloud` | `https://nyc1.livekit-telnyx.com` |
| `LIVEKIT_API_KEY` | LiveKit Cloud key | Telnyx API key |
| `LIVEKIT_API_SECRET` | LiveKit Cloud secret | Your LiveKit API secret |

## What doesn't change

- Your agent code
- SDK usage
- `lk` CLI commands
- Dockerfiles
- Room management, dispatch rules

## Steps

1. **Create a Telnyx account** at [portal.telnyx.com](https://portal.telnyx.com)
2. **Generate a Telnyx API key** in the portal
3. **Register with the platform** (one-time):
   ```bash
   curl -s -X POST "https://.livekit-telnyx.com/provision" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "my-project",
       "api_key": "'$TELNYX_API_KEY'",
       "api_secret": "'$LIVEKIT_API_SECRET'"
     }'
   ```
4. **Update your environment variables** with the values above
5. **Deploy to Telnyx:**
   ```bash
   lk agent deploy . --secrets TELNYX_API_KEY=
   ```
5. **Verify:** `lk room list` to confirm connectivity
6. **(Optional)** Install the [Telnyx plugin](/docs/livekit/build) for on-prem STT, TTS, and LLM
7. **(Optional)** [Buy a Telnyx number](/docs/livekit/telephony) for built-in telephony

## What you gain

- **Built-in telephony, no third-party SIP fees** — On other platforms, you pay third-party SIP fees on top of your usage. On Telnyx, those are gone entirely.
- **Ultra-low latency AI on Telnyx GPUs** — STT, TTS, and LLM colocated in every region ~2ms from your agents. No round-trips to external APIs.
- **One platform, one bill** — Compute, models, telephony, and phone numbers on a single Telnyx invoice. No vendor sprawl.

## Rolling back

It's just environment variables. Point them back at LiveKit Cloud and redeploy.

---

### From Self-Hosted

> Source: https://developers.telnyx.com/docs/livekit/migration/from-self-hosted.md

Keep your agents, ditch the infrastructure. No more managing Kubernetes clusters, TURN servers, SIP services, or autoscaling.

## What Telnyx replaces

- LiveKit SFU server
- SIP service / Otel SIP
- TURN/STUN servers
- Container orchestration / autoscaling
- TLS termination and load balancing
- Monitoring infrastructure

## What stays the same

- Your agent code
- SDK calls
- Room management logic
- Dispatch rules

## Steps

1. **Create a Telnyx account** at [portal.telnyx.com](https://portal.telnyx.com)
2. **Generate a Telnyx API key** in the portal
3. **Register with the platform** (one-time):
   ```bash
   curl -s -X POST "https://.livekit-telnyx.com/provision" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "my-project",
       "api_key": "'$TELNYX_API_KEY'",
       "api_secret": "'$LIVEKIT_API_SECRET'"
     }'
   ```
4. **Update your agent** to point at `https://nyc1.livekit-telnyx.com` (or your [preferred region](/docs/livekit/connect#available-regions))
4. **Move secrets** to the platform:
   ```bash
   lk agent deploy . --secrets TELNYX_API_KEY=,OTHER_SECRET=
   ```
5. **Re-create dispatch rules** on the Telnyx platform
6. **Update SIP configuration** to point at Telnyx [SIP endpoints](/docs/livekit/telephony)
7. **Verify** your agent is running: `lk room list`
8. **Decommission** your self-hosted infrastructure

## What you gain

- **No infra management** — No Kubernetes, no TURN, no Redis for multi-region.
- **Built-in SIP, no third-party SIP fees** — On other platforms, you pay third-party SIP fees on top of your usage. On Telnyx, those are gone entirely.
- **Managed autoscaling** — Platform handles container lifecycle.
- **Ultra-low latency AI on Telnyx GPUs** — STT, TTS, and LLM colocated in every region ~2ms from your agents. No round-trips to external APIs.

---

## Build

### Build

> Source: https://developers.telnyx.com/docs/livekit/build.md

**First time building?** Complete [Quickstart — Step 1](/docs/livekit/quickstart#step-1-configure-the-cli) to configure your CLI and register with the platform.

## 1. Install the plugin

```bash
pip install "telnyx-livekit-plugin @ git+https://github.com/team-telnyx/telnyx-livekit-plugin.git#subdirectory=telnyx-livekit-plugin"
```

This is the Telnyx-maintained plugin, which includes the latest features and fixes ahead of the upstream `livekit-plugins-telnyx` PyPI package. We host our own release to iterate faster than the upstream cadence allows. Use the git install above for the current recommended version.

*[Plugin source on GitHub](https://github.com/team-telnyx/telnyx-livekit-plugin)*

## 2. Write your agent

Create `agent.py`:

```python
import asyncio
from livekit.agents import Agent, AgentSession, JobContext, RoomInputOptions
from livekit.plugins import openai, silero, telnyx

class MyAgent(Agent):
    def __init__(self):
        super().__init__(instructions="You are a helpful voice assistant.")

    async def on_enter(self):
        self.session.generate_reply(
            instructions="Greet the caller and ask how you can help."
        )

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        stt=telnyx.STT(
            transcription_engine="Deepgram",
            base_url="wss://api.telnyx.com/v2/speech-to-text/transcription",
        ),
        llm=openai.LLM.with_telnyx(model="zai-org/GLM-5.1-FP8"),
        tts=telnyx.TTS(
            voice="Telnyx.NaturalHD.astra",
            sample_rate=24000,
        ),
        vad=silero.VAD.load(),
    )

    await ctx.connect()
    await session.start(
        agent=MyAgent(),
        room=ctx.room,
        room_input_options=RoomInputOptions(),
    )

    disconnect_event = asyncio.Event()

    @ctx.room.on("disconnected")
    def on_disconnect(*args):
        disconnect_event.set()

    await disconnect_event.wait()
```

The only Telnyx-specific parts are the `stt`, `tts`, and `llm` — everything else is standard LiveKit.

## 3. Add a requirements file

Create `requirements.txt`:

```
livekit-agents
livekit-plugins-openai
livekit-plugins-silero
telnyx-livekit-plugin @ git+https://github.com/team-telnyx/telnyx-livekit-plugin.git#subdirectory=telnyx-livekit-plugin
```

## 4. Deploy

```bash
lk agent deploy . --secrets TELNYX_API_KEY=$TELNYX_API_KEY
```

The platform builds your image in-cluster, deploys it, and starts the worker. Check the status:

```bash
lk agent list
```

Tail logs once it's running:

```bash
lk agent logs --id 
```

## Swap models

The example above uses Telnyx-hosted defaults. Swap any component independently:

- **STT** — Deepgram, Nova-3, Nova-2, Flux → [STT plugin](/docs/livekit/models/stt)
- **TTS** — Telnyx Natural HD, MiniMax, Rime, ElevenLabs (BYOK), Azure → [TTS plugin](/docs/livekit/models/tts)
- **LLM** — GPT-4o-mini, Kimi-K2.6, Claude (BYOK) → [LLM plugin](/docs/livekit/models/llm)

## Next steps

- [Telephony](/docs/livekit/telephony) — Connect your agent to a phone number
- [Deploy reference](/docs/livekit/deploy) — Secrets, rollbacks, multi-region

---

## Deploy

### Deploy

> Source: https://developers.telnyx.com/docs/livekit/deploy.md

Same commands as LiveKit Cloud. `lk agent deploy` uploads your code, builds a container image on Telnyx's build service, and deploys the worker.

**First time deploying?** Complete [Quickstart — Step 1](/docs/livekit/quickstart#step-1-configure-the-cli) to configure your CLI and register with the platform.

## 1. Create your agent

```bash
lk agent create .
```

Registers the agent and writes the agent ID to `livekit.toml`. Skip this if you've already created the agent.

## 2. Deploy

```bash
lk agent deploy . --secrets TELNYX_API_KEY=$TELNYX_API_KEY
```

Subsequent deploys roll out a new version.

## 3. Check status

```bash
lk agent list
```

## 4. Tail logs

```bash
lk agent logs --id 
```

For build logs:

```bash
lk agent logs --id  --log-type build
```

## 5. Update secrets

Add or update secrets on a running agent:

```bash
lk agent update-secrets  --secrets "OPENAI_API_KEY="
```

## 6. Rollback

```bash
lk agent rollback 
```

## What gets auto-injected

The platform injects these into your agent's environment at runtime — you don't need to set them manually:

- `LIVEKIT_URL`
- `LIVEKIT_API_KEY` — your Telnyx API key
- `LIVEKIT_API_SECRET`

## More

- [Secrets](/docs/livekit/deploy/secrets) — Managing API keys and sensitive config
- [Configuration](/docs/livekit/deploy/configuration) — Regions, multi-agent projects, env vars
- [Management](/docs/livekit/deploy/management) — What Telnyx manages vs. what you control

---

### Configuration

> Source: https://developers.telnyx.com/docs/livekit/deploy/configuration.md

## Regions

Deploy to the region closest to your users. See [Regions](/docs/livekit/regions) for all available endpoints.

## Environment variables and livekit.toml

Set `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` as environment variables. You also need a `livekit.toml` in your project directory that defines the subdomain and agent ID:

```toml
[project]
subdomain = "nyc1"

[agent]
id = ""
```

`lk agent create` writes the agent ID to `livekit.toml`. Don't edit the `[agent]` section manually. If you clone an example repo, remove the `[agent]` section before running `lk agent create` so a fresh ID is generated.

For multi-agent projects, use the `--config` flag to point at different TOML files:

```bash
lk agent deploy . --config agent-a.toml
lk agent deploy . --config agent-b.toml
```

## Multiple environments

Use separate API keys for dev, staging, and production environments. Each key operates independently.

## Log access

Stream logs from your running agent:

```bash
lk agent logs 
```

Log forwarding to third-party services (Datadog, Sentry, CloudWatch) is coming soon.

---

### Secrets

> Source: https://developers.telnyx.com/docs/livekit/deploy/secrets.md

## Setting secrets on deploy

Pass secrets when you deploy:

```bash
lk agent deploy . --secrets TELNYX_API_KEY=
```

To set additional secrets after deploy:

```bash
lk agent update-secrets  --secrets "OPENAI_API_KEY="
```

## Updating secrets

Update secrets on a running agent:

```bash
lk agent update-secrets  --secrets "KEY=value"
```

## Auto-injected variables

The platform automatically injects these into your agent's environment at runtime:

- `LIVEKIT_URL`
- `LIVEKIT_API_KEY` (your Telnyx API key — used for both platform auth and model access)
- `LIVEKIT_API_SECRET`

You don't need to set these manually. Note: `LIVEKIT_API_KEY` is your Telnyx API key. Telnyx can revoke it if needed, giving you a single credential to manage.

## Local development

For local development, use a `.env.local` file:

```bash
TELNYX_API_KEY=your-key-here
LIVEKIT_URL=https://nyc1.livekit-telnyx.com
LIVEKIT_API_KEY=your-key
LIVEKIT_API_SECRET=your-secret
```

Secrets set via the CLI are encrypted at rest and injected at runtime. They cannot be retrieved after being set.

---

### Management & Access

> Source: https://developers.telnyx.com/docs/livekit/deploy/management.md

## Access model

All platform interaction is through the `lk` CLI and the [Telnyx Portal](https://portal.telnyx.com). There is no direct access to underlying infrastructure (no kubectl, no SSH).

## What Telnyx manages

- LiveKit SFU (media server)
- SIP service (built-in telephony)
- Agent container runtime and orchestration
- Autoscaling
- TLS/SSL termination and load balancing
- Health checks and rolling deploys

## What you control

| Capability | How |
|-----------|-----|
| Agent code and Dockerfile | `lk agent deploy .` |
| Secrets | `lk agent deploy --secrets` / `lk agent update-secrets` |
| Rollback | `lk agent rollback` |
| Logs | `lk agent logs` |
| Phone numbers | Telnyx Portal |
| SIP connections | Telnyx Portal |
| Model selection | Telnyx plugin or BYOK |

## Current limitations

- No volume mounts or persistent storage
- No custom networking or network policies
- No privileged containers
- No custom domains
- No direct database access — use external services with secrets

See [Compatibility](/docs/livekit/compatibility) for the full list of supported and unsupported features.

---

## Plugin Reference

### Overview

> Source: https://developers.telnyx.com/docs/livekit/models.md

All models are accessed through the [Telnyx plugin](/docs/livekit/build). Models run on Telnyx GPUs, so whether you're using the plugin from LiveKit Cloud or deployed on the Telnyx platform, you get on-prem inference without managing infrastructure.

    Deepgram Nova-3, Nova-2, and Flux — hosted on Telnyx.
    Extensive voice library across multiple providers and models.
    Hosted open-source and proprietary models via BYOK.

---

### STT

> Source: https://developers.telnyx.com/docs/livekit/models/stt.md

Telnyx hosts Deepgram models on dedicated GPUs. Access them through the Telnyx plugin:

```python
from livekit.plugins import telnyx

stt = telnyx.deepgram.STT(model="nova-3", language="en")
```

The plugin provides two STT classes:

- **`telnyx.deepgram.STT`** — Recommended. Connects to Deepgram models hosted on Telnyx GPUs. Takes a `model` parameter (`nova-3`, `nova-2`, `flux`).
- **`telnyx.STT`** — Connects to Telnyx's own transcription engine (default) or Deepgram via `transcription_engine="Deepgram"`. Takes a `transcription_engine` parameter instead of `model`.

For most use cases, `telnyx.deepgram.STT` is the simpler interface.

*[Plugin source on GitHub](https://github.com/team-telnyx/telnyx-livekit-plugin)*

## Available models

### Nova-3 (recommended)

Latest generation, best accuracy.

```python
stt = telnyx.deepgram.STT(
    model="nova-3",
    language="en",
    interim_results=True,
    keyterm=["YourBrand", "custom-term"],  # keyword boosting
)
```

### Nova-2

Previous generation, stable and reliable. Uses weighted keyword boosting.

```python
stt = telnyx.deepgram.STT(
    model="nova-2",
    language="en",
    interim_results=True,
    keywords=["YourBrand:2.0", "custom-term:1.5"],
)
```

### Flux

Experimental, with built-in end-of-turn detection. Designed for real-time voice agents.

```python
stt = telnyx.deepgram.STT(
    model="flux",
    language="en",
    interim_results=True,
    keyterm=["YourBrand", "custom-term"],
    eot_threshold=0.5,
    eot_timeout_ms=3000,
    eager_eot_threshold=0.3,
)
```

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `model` | `nova-3` | Model to use (`nova-3`, `nova-2`, `flux`) |
| `language` | `en` | Language code |
| `interim_results` | `True` | Stream partial transcriptions |
| `keyterm` | — | Keyword boosting (Nova-3, Flux) |
| `keywords` | — | Weighted keyword boosting (Nova-2) |
| `eot_threshold` | — | End-of-turn confidence threshold (Flux only) |
| `eot_timeout_ms` | — | End-of-turn timeout in ms (Flux only) |
| `eager_eot_threshold` | — | Eager end-of-turn threshold (Flux only) |

---

### TTS

> Source: https://developers.telnyx.com/docs/livekit/models/tts.md

Telnyx offers an extensive library of voices across multiple providers and models, with broad language and accent support. Access them through the Telnyx plugin:

```python
from livekit.plugins import telnyx

tts = telnyx.TTS(voice="Telnyx.NaturalHD.astra")
```

## Voice ID format

Voice IDs follow the pattern `Provider.Model.voice_name`. To find a voice:

1. Browse the [voice library](https://developers.telnyx.com/docs/tts-stt/tts-available-voices/index)
2. Copy the voice ID (e.g. `Telnyx.NaturalHD.astra`)
3. Pass it to `telnyx.TTS(voice="...")`

## Examples

```python
# Telnyx Natural HD
tts = telnyx.TTS(voice="Telnyx.NaturalHD.astra")

# MiniMax Speech 2.8 Turbo
tts = telnyx.TTS(voice="MiniMax.speech-2.8-turbo.Narrator")

# Rime Arcana V3
tts = telnyx.TTS(voice="Rime.ArcanaV3.astra")
```

## Available providers and models

| Provider | Models |
|----------|--------|
| **Telnyx** | NaturalHD, Ultra |
| **MiniMax** | speech-02-turbo, speech-2.6-turbo, speech-2.8-turbo |
| **Rime** | ArcanaV3, KokoroTTS |
| **AWS** | Polly (Neural voices) |
| **Azure** | Neural voices |
| **Inworld** | Coming soon |
| **ResembleAI** | Coming soon |

Browse all voices and models in the [voice library →](https://developers.telnyx.com/docs/tts-stt/tts-available-voices/index)

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `voice` | — | Voice ID (e.g. `Telnyx.NaturalHD.astra`) |
| `sample_rate` | `16000` | Audio sample rate in Hz |

---

### LLM

> Source: https://developers.telnyx.com/docs/livekit/models/llm.md

Telnyx hosts models with an OpenAI-compatible API. No concurrency limits. Use the standard OpenAI plugin with the `.with_telnyx()` helper:

```python
from livekit.plugins import openai

llm = openai.LLM.with_telnyx(model="zai-org/GLM-5.1-FP8")
```

## About `.with_telnyx()`

This is a built-in static method on `openai.LLM` in the official [`livekit-plugins-openai`](https://pypi.org/project/livekit-plugins-openai/) package, maintained by LiveKit — not a Telnyx package or fork. It works the same way as the other OpenAI-compatible helpers in that package (`.with_azure()`, `.with_fireworks()`, etc.): it sets `base_url` to Telnyx's OpenAI-compatible inference endpoint (`https://api.telnyx.com/v2/ai/openai`) and reads your `TELNYX_API_KEY` from the environment. You don't need any additional packages beyond `livekit-plugins-openai`.

## Hosted models

These run on Telnyx infrastructure — no external API key needed, just your `TELNYX_API_KEY`:

| Model | Description |
|-------|-------------|
| `moonshotai/Kimi-K2.6` | Moonshot AI — voice AI, with thinking disabled **(Recommended)** |
| `zai-org/GLM-5.1-FP8` | Zhipu AI — most efficient reasoning, function calling |
| `MiniMaxAI/MiniMax-M2.7` | MiniMax — cheapest, high intelligence |

{/* TODO: Add top proprietary Telnyx models */}

## Proprietary models (BYOK)

For models like GPT-4o or Claude, Telnyx proxies the request using your own API key. Add your provider key in the [Telnyx Portal](https://portal.telnyx.com) under Inference settings.

```python
# Proprietary model via BYOK (bring your own key)
llm = openai.LLM.with_telnyx(model="openai/gpt-4o-mini")
```

[Full models list →](/docs/inference/models)

---

## Observability

### Observability

> Source: https://developers.telnyx.com/docs/livekit/observability.md

## What's available today

### Agent logs

Stream logs from your running agent via the CLI:

```bash
lk agent logs 
```

This gives you stdout/stderr from your agent in real time — same as LiveKit Cloud's log access.

## Coming very soon

Traces, metrics, and session debugging are on our [roadmap](/docs/livekit/compatibility#coming-soon).

---

## Telephony

### Telephony

> Source: https://developers.telnyx.com/docs/livekit/telephony.md

Telnyx is the carrier. Buy a number, connect it to your agent — no third-party SIP trunk setup, no FQDN auth dance. Calls route on-net from Telnyx SIP directly to your agent.

For setup steps, see the [Quick Start](/docs/livekit/quickstart).

## Supported

### Inbound calls

Inbound calls are routed to your agent via SIP dispatch rules. When someone calls your DID, Telnyx forwards it to the LiveKit SIP service, which dispatches it to your agent based on the rules you configure.

### Outbound calls

Use the `lk` CLI to place an outbound call into a room:

```bash
lk sip participant create \
  --room "my-room" \
  --trunk "" \
  --call "+15551234567" \
  --identity "outbound-caller"
```

### DTMF

DTMF tones are supported via RFC 2833/4733. Tones are forwarded to your agent as events and can be handled in code.

### SIP headers

Pass call metadata through to your agent using `headers_to_attributes`. Header values are mapped to LiveKit participant attributes, available in your agent at runtime.

### HD voice

Telnyx supports two HD voice codecs for higher-quality audio on SIP calls:

- **G.722** — Wideband audio at 16 kHz sample rate. Enabled by default on all Telnyx SIP connections. No additional configuration needed.
- **Opus** — Wideband audio at 48 kHz sample rate. Requires SRTP encryption on both sides — enable OPUS in your Telnyx SIP connection's inbound codec list and set `media_encryption: ALLOW` on your LiveKit inbound trunk. Delivers the highest audio quality for voice AI agents.

Both codecs are negotiated automatically during SIP call setup. If the remote side supports Opus, it will be preferred over G.722.

## Not yet supported

These features require [Enterprise SIP](/docs/livekit/compatibility#coming-soon), which is on the roadmap.

- **Call transfers (REFER / warm transfer)**

---

## Reference

### Architecture

> Source: https://developers.telnyx.com/docs/livekit/architecture.md

Telnyx LiveKit is a managed platform for deploying voice AI agents at scale. You ship agent code. The platform handles containers, scaling, SIP, and AI inference — colocated in each region.

## Agents

Each agent you deploy is an isolated worker. Deploy as many as you need — a restaurant bot, a support agent, a scheduling assistant — each running independently under your account.

```
lk agent deploy .   →   isolated worker, autoscaled, managed containers
```

Agents are deployed per-account with full namespace isolation. Your rooms, SIP trunks, and dispatch rules are scoped to your API key and never visible to other tenants.

## Autoscaling

The platform watches active room load and scales your agent workers up and down automatically. You don't configure `load_fnc` or `load_threshold` — the platform manages this.

- **Scale up** — new workers spin up as concurrent calls increase
- **Scale down** — idle workers are drained and removed
- **Health checks** — unhealthy containers are replaced automatically with rolling deploys

## Inbound call flow

```
Caller → PSTN → Telnyx SIP → LiveKit SIP Bridge → Room → Agent Worker
```

Because Telnyx is both the carrier and the platform, the SIP leg is on-net — no external SIP trunk hop, no PSTN egress to a third party. The call lands directly in a LiveKit room where your agent is waiting.

## AI inference

STT, TTS, and LLM inference runs on Telnyx GPUs colocated with the agent runtime — approximately 2ms from your agent. No round-trips to external APIs on the hot path.

```
Agent ──2ms──▶ Telnyx STT / TTS / LLM
```

You can also bring your own provider keys (OpenAI, Anthropic, etc.) — those route externally.

## Regions

Each region is a full stack: SFU, SIP, agent runtime, and AI inference. See [Regions](/docs/livekit/regions) for available endpoints.

---

### Regions

> Source: https://developers.telnyx.com/docs/livekit/regions.md

## Platform endpoints

| Region | Endpoint |
|--------|----------|
| New York | `https://nyc1.livekit-telnyx.com` |
| San Francisco | `https://sfo3.livekit-telnyx.com` |
| Atlanta | `https://atl1.livekit-telnyx.com` |
| Sydney | `https://syd1.livekit-telnyx.com` |

## SIP endpoints

| Region | SIP Endpoint |
|--------|-------------|
| New York | `nyc1.sip.livekit-telnyx.com` |
| San Francisco | `sfo3.sip.livekit-telnyx.com` |
| Atlanta | `atl1.sip.livekit-telnyx.com` |
| Sydney | `syd1.sip.livekit-telnyx.com` |

Choose the region closest to your users for the lowest latency.

---

### Limits

> Source: https://developers.telnyx.com/docs/livekit/limits.md

## Build limits

| Limit | Value |
|-------|-------|
| Build timeout | 10 minutes |
| Build context size | 1 GB |

## Agent limits

| Limit | Value |
|-------|-------|
| Max concurrent agents | Contact us |
| Max concurrent sessions per agent | Contact us |

## Telephony limits

| Limit | Value |
|-------|-------|
| Max concurrent calls | Contact us |

For specific limit increases, contact your Telnyx account team.

---

### Pricing

> Source: https://developers.telnyx.com/docs/livekit/pricing.md

All services — compute, models, and telephony — are billed on a single Telnyx invoice. On other platforms, you pay third-party SIP fees on top of your usage. On Telnyx, those are gone entirely.

##  Telnyx Ultra — Platform Exclusive

Our highest-fidelity voice. Available exclusively for agents deployed on LiveKit on Telnyx, not through the plugin alone.

Head over to the [TTS voice library](https://developers.telnyx.com/docs/tts-stt/tts-available-voices/index) to check out the variety of voices, languages, and accents we offer.

## STT

See [telnyx.com/pricing/speech-to-text](https://telnyx.com/pricing/speech-to-text) for current rates.

## TTS

See [telnyx.com/pricing/text-to-speech](https://telnyx.com/pricing/text-to-speech) for current rates.

## LLM

See [telnyx.com/pricing/conversational-ai](https://telnyx.com/pricing/conversational-ai) for current rates.

---