LiveKit Phone Numbers | LiveKit docs

Overview

LiveKit Phone Numbers lets you purchase and manage US phone numbers for voice applications. It provides the telephony infrastructure and phone number inventory, without requiring separate SIP trunk configuration. Buy local or toll-free numbers directly through LiveKit and assign them to voice agents using dispatch rules.

Buy numbers directly: Select local or toll-free US numbers for inbound calling with your preferred area code.
Streamlined setup: Purchase phone numbers and configure voice agents without SIP trunk complexity.
High-definition (HD) voice: Ensure clear, professional audio quality on all calls, from agent dialogue to hold music.
Unified management: Use LiveKit Cloud to procure and manage numbers, configure dispatch rules, and review call metrics and logs.

You can manage your phone numbers using the LiveKit Cloud dashboard, LiveKit CLI, or the Phone Numbers APIs.

Setting up a LiveKit phone number

To set up a LiveKit phone number, you need to purchase a phone number and assign it to a dispatch rule. The following steps guide you through the process.

Step 1: Search for an available number

Search for available phone numbers by country and area code.

Search for available numbers by area code:

Sign in to the LiveKit Cloud dashboard.
Select Telephony → Phone Numbers.
Select Buy a number.
Select the search icon and enter an area code.

Search for phone numbers in the United States with area code 415:

lk number search --country-code US --area-code 415

Step 2: Buy a number

Select an available phone number and purchase it.

After you search for available numbers, purchase the number by clicking Buy in the row with the number you want to purchase:

Select Buy for the number you want to purchase.
Select Confirm purchase.

To buy the number +14155550100, run the following command:

lk number purchase --numbers +14155550100

Step 3: Assign the number to a dispatch rule

Assign the number to a dispatch rule. LiveKit recommends using explicit dispatch for agents that receive inbound calls. Define the agent you want to respond to calls to a number in the dispatch rule. To learn more, see Dispatch from inbound SIP calls.

After you successfully purchase a phone number, you can select Options to assign or create a dispatch rule for the number. Otherwise, use the following steps to assign a dispatch rule:

Navigate to the Phone Numbers page and find the number you want to assign a dispatch rule to.
Select the more menu (⋮) and select Assign dispatch rule.
Select the dispatch rule you want to assign to the number.
Select Save.

For example, to assign a phone number to a dispatch rule, replace the <PHONE_NUMBER_ID> and <DISPATCH_RULE_ID> placeholders, and run the following command:

lk number update --id <PHONE_NUMBER_ID> --sip-dispatch-rule-id <DISPATCH_RULE_ID>

Find your phone number ID

You can find your phone number ID by listing all phone numbers using the lk number list command.

Create an agent that responds to inbound calls

Follow the Voice AI quickstart to create an agent. Start your agent and call your phone number.

Considerations

The following limitations and considerations apply to LiveKit Phone Numbers:

Available only in the US. Support for additional countries is coming in a future release.
Only inbound calling is supported. Support for outbound calling is coming in a future release.
Forwarding calls using the TransferSipParticipant API is not yet supported.
If you release a phone number before the end of the month, you are still billed for the entirety of the month. For details on pricing, see the LiveKit Phone Numbers pricing page.

CLI reference

The LiveKit CLI provides phone number management commands for searching, purchasing, and managing phone numbers for your SIP applications. Prefix all phone number commands with lk number.

For instructions on installing the CLI, see the LiveKit CLI Getting started guide.

lk number [command] [command options]

CLI version requirement

Update the CLI regularly to ensure you have the latest version. You must have an up-to-date CLI to manage phone numbers. See Update the CLI for instructions.

Search

Search available phone numbers in inventory for purchase.

lk number search [options]

Options for search:

--country-code STRING: Filter by country code (for example, "US," "CA"). Required.
--area-code STRING: Filter by area code (for example, "415").
--limit INT: Maximum number of results. Default: 50.
--json, -j: Output as JSON. Default: false.

Examples

Search for phone numbers in the US with area code 415:

lk number search --country-code US --area-code 415 --limit 10

Search for phone numbers with JSON output:

lk number search --country-code US --area-code 415 --json

Purchase

Purchase phone numbers from inventory.

lk number purchase [options]

Options for purchase:

--numbers STRING: Phone numbers to purchase (for example, "+16505550010"). Required.
--sip-dispatch-rule-id STRING: SIP dispatch rule ID to apply to all purchased numbers.

Examples

Purchase a single phone number:

lk number purchase --numbers +16505550010

List

List phone numbers for a project.

lk number list [options]

Options for list:

--limit INT: Maximum number of results. Default: 50.
--status STRING: Filter by statuses: active, pending, released. You can specify multiple statuses by repeating the flag.
--sip-dispatch-rule-id STRING: Filter by SIP dispatch rule ID.
--json, -j: Output as JSON. Default: false.

Examples

List all activephone numbers:

lk number list

List active and released phone numbers:

lk number list --status active --status released

Get

Get details for a specific phone number.

lk number get [options]

Options for get:

--id STRING: Phone number ID for direct lookup.
--number STRING: Phone number string for lookup (for example, "+16505550010").

Note: you must specify either --id or --number.

Examples

Get phone number by ID:

lk number get --id <PHONE_NUMBER_ID>

Get phone number by number string:

lk number get --number +16505550010

Update

Update a phone number configuration.

lk number update [options]

Options for update:

--id STRING: Phone number ID for direct lookup.
--number STRING: Phone number string for lookup.
--sip-dispatch-rule-id STRING: SIP dispatch rule ID to assign to the phone number.

Note: you must specify either --id or --number.

Examples

Update phone number dispatch rule by ID:

lk number update --id <PHONE_NUMBER_ID> --sip-dispatch-rule-id <DISPATCH_RULE_ID>

Update phone number dispatch rule by number:

lk number update \
  --number +16505550010 \
  --sip-dispatch-rule-id <DISPATCH_RULE_ID>

Release

Release phone numbers by ID or phone number string.

lk number release [options]

Options for release:

--ids STRING: Phone number ID for direct lookup.
--numbers STRING: Phone number string for lookup.

Note: you must specify either --ids or --numbers.

Examples

Release phone numbers by ID:

lk number release --ids <PHONE_NUMBER_ID>

Release phone numbers by number strings:

lk number release --numbers +16505550010

Additional resources

The following topics provide more information on managing LiveKit Phone Numbers and LiveKit SIP.

Dispatch rules

Create dispatch rules to determine how callers to your LiveKit Phone Number are dispatched to rooms.

Phone Number APIs

Reference for the phone number management commands in the LiveKit CLI.