Telephony

Overview

Use the lk sip commands to manage inbound trunks, outbound trunks, dispatch rules, and SIP participants. Use the lk number commands to search, purchase, and manage LiveKit Phone Numbers. For concepts and configuration options, see the Telephony guides. To install the CLI, see Install the CLI.

lk sip [command [command options]]
lk number [command [command options]]

Commands run against your default project. To target another project, pass the global --project NAME flag.

Request files

The create and update subcommands for trunks and dispatch rules, and sip participant create, accept a JSON request file as a positional argument. Use a file to set fields that have no flag, such as allowed_addresses or room_config. Field names follow the SIP API, in snake_case or camelCase. Pass a path, - to read from stdin, or the JSON itself as a quoted string.

With create, flags override the matching fields in the file, and passing several files creates one resource per file.

Media options

The trunk and dispatch rule create and update commands, and sip participant create, share these flags:

• --media-enc VALUE: Media encryption: disable, allow, or require. See Secure trunking.
• --codecs VALUE: Codec to offer, as NAME or NAME/RATE, in addition to the default codecs. Repeatable or comma-separated.
• --no-default-codecs: Offer only the codecs set with --codecs.

Inbound trunks

Inbound trunks accept calls from your SIP trunking provider. To learn more, see SIP inbound trunk. Aliases: in, inbound-trunk.

lk sip inbound [command [command options]]

List

List all inbound trunks.

lk sip inbound list [--json]

• --json, -j: Output as JSON. Default: false.

Create

Create an inbound trunk and print its ID. A trunk must set numbers, allowed_addresses, or both auth_username and auth_password.

lk sip inbound create [options] [REQUEST_FILE]

• REQUEST_FILE: A CreateSIPInboundTrunkRequest as JSON.
• --name NAME: Trunk name.
• --numbers NUMBER: Phone number the trunk accepts calls for. Repeatable or comma-separated.
• --auth-user USERNAME: Username callers must authenticate with.
• --auth-pass PASSWORD: Password callers must authenticate with.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip inbound create --name "My trunk" --numbers +15105550100

Create a trunk from a file, with credentials passed as flags:

{
  "trunk": {
    "name": "My trunk",
    "numbers": ["+15105550100"],
    "allowed_addresses": ["203.0.113.0/24"]
  }
}

lk sip inbound create inbound-trunk.json \
  --auth-user "$SIP_AUTH_USERNAME" \
  --auth-pass "$SIP_AUTH_PASSWORD"

Update

Update an inbound trunk. Flags change only the fields you set. A request file replaces the whole trunk.

lk sip inbound update --id TRUNK_ID [options]
lk sip inbound update [--id TRUNK_ID] REQUEST_FILE

• REQUEST_FILE: A SIPInboundTrunkInfo as JSON, without the trunk wrapper.
• --id TRUNK_ID: Trunk to update. Required unless the file sets sip_trunk_id.
• --name NAME: New trunk name.
• --numbers NUMBER: New phone numbers. Replaces the existing list.
• --auth-user USERNAME: New authentication username.
• --auth-pass PASSWORD: New authentication password.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip inbound update --id <trunk-id> \
  --name "Support line" \
  --numbers +15105550100,+15105550101

Replace a trunk with the contents of a file:

lk sip inbound update --id <trunk-id> inbound-trunk.json

Delete

Delete one or more inbound trunks.

lk sip inbound delete TRUNK_ID [TRUNK_ID...]

Outbound trunks

Outbound trunks store the provider settings LiveKit uses to place calls. To learn more, see SIP outbound trunk. Aliases: out, outbound-trunk.

lk sip outbound [command [command options]]

List

List all outbound trunks.

lk sip outbound list [--json]

• --json, -j: Output as JSON. Default: false.

Create

Create an outbound trunk and print its ID. A trunk requires an address and at least one number.

lk sip outbound create [options] [REQUEST_FILE]

• REQUEST_FILE: A CreateSIPOutboundTrunkRequest as JSON.
• --name NAME: Trunk name.
• --address HOSTNAME: Your provider's SIP endpoint, for example sip.telnyx.com.
• --transport VALUE: auto, udp, tcp, or tls. Default: auto.
• --destination-country CODE: ISO 3166-1 alpha-2 code, such as US, for region pinning.
• --numbers NUMBER: Phone number to call from. Repeatable or comma-separated. Use * to allow any number.
• --auth-user USERNAME: Username for your provider.
• --auth-pass PASSWORD: Password for your provider.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip outbound create \
  --name "My outbound trunk" \
  --address sip.telnyx.com \
  --numbers +15105550100 \
  --auth-user "$SIP_AUTH_USERNAME" \
  --auth-pass "$SIP_AUTH_PASSWORD"

Create a trunk from a request file that uses TLS:

lk sip outbound create outbound-trunk.json --transport tls

Update

Update an outbound trunk. Flags change only the fields you set. A request file replaces the whole trunk.

lk sip outbound update --id TRUNK_ID [options]
lk sip outbound update [--id TRUNK_ID] REQUEST_FILE

• REQUEST_FILE: A SIPOutboundTrunkInfo as JSON, without the trunk wrapper.
• --id TRUNK_ID: Trunk to update. Required unless the file sets sip_trunk_id.
• --name NAME: New trunk name.
• --address HOSTNAME: New SIP endpoint.
• --transport VALUE: New transport: auto, udp, tcp, or tls.
• --destination-country CODE: New destination country.
• --numbers NUMBER: New phone numbers. Replaces the existing list.
• --auth-user USERNAME: New authentication username.
• --auth-pass PASSWORD: New authentication password.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip outbound update --id <trunk-id> --transport tls

Replace a trunk with the contents of a file:

lk sip outbound update --id <trunk-id> outbound-trunk.json

Delete

Delete one or more outbound trunks.

lk sip outbound delete TRUNK_ID [TRUNK_ID...]

Dispatch rules

Dispatch rules control which room an inbound call joins and which agents are dispatched to it. To learn more, see Dispatch rule. Alias: dispatch-rule.

lk sip dispatch [command [command options]]

List

List all dispatch rules. A rule that applies to all trunks shows <any> in the SipTrunks column.

lk sip dispatch list [--json]

• --json, -j: Output as JSON. Default: false.

Create

Create a dispatch rule and print its ID. Set the rule type in the file or with one of --direct, --caller, or --callee, which are mutually exclusive.

lk sip dispatch create [options] [REQUEST_FILE]

• REQUEST_FILE: A CreateSIPDispatchRuleRequest as JSON. Use a file to set room_config, a pin, or attributes.
• --name NAME: Rule name.
• --trunks TRUNK_ID: Inbound trunk the rule applies to. Repeatable or comma-separated. Omit to apply to all trunks.
• --direct ROOM: Direct rule that places every caller in ROOM.
• --caller PREFIX, --individual PREFIX: Individual rule that places each caller in a new room named with PREFIX.
• --callee PREFIX: Callee rule that names the room after PREFIX and the called number.
• --randomize: With --callee, give each call its own room.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip dispatch create \
  --name "Individual rule" \
  --trunks <trunk-id> \
  --caller call-

Create a rule that dispatches an agent:

{
  "dispatchRule": {
    "name": "Agent rule",
    "rule": {
      "dispatchRuleIndividual": {
        "roomPrefix": "call-"
      }
    },
    "roomConfig": {
      "agents": [{ "agentName": "inbound-agent" }]
    }
  }
}

lk sip dispatch create dispatch-rule.json --trunks <trunk-id>

Update

Update a dispatch rule. Flags change only the fields you set, and --direct, --caller, or --callee replaces the rule type. A request file replaces the whole rule.

lk sip dispatch update --id RULE_ID [options]
lk sip dispatch update [--id RULE_ID] REQUEST_FILE

• REQUEST_FILE: A SIPDispatchRuleInfo as JSON, without the dispatch_rule wrapper.
• --id RULE_ID: Rule to update. Required unless the file sets sip_dispatch_rule_id.
• --name NAME: New rule name.
• --trunks TRUNK_ID: New trunk IDs. Replaces the existing list. To apply the rule to all trunks again, replace the rule with a file that omits trunk_ids.
• --direct ROOM, --caller PREFIX, --callee PREFIX, --randomize: New rule type. See sip dispatch create.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip dispatch update --id <dispatch-rule-id> \
  --trunks <trunk-id-1>,<trunk-id-2>

Replace a rule with the contents of a file:

lk sip dispatch update --id <dispatch-rule-id> dispatch-rule.json

Delete

Delete one or more dispatch rules.

lk sip dispatch delete RULE_ID [RULE_ID...]

SIP participants

A SIP participant represents a phone call in a LiveKit room. Use these commands to place outbound calls and transfer calls.

lk sip participant [command [command options]]

Create

Place an outbound call and add the callee to a room. Each call needs a trunk, a number to call, and a room, set with flags or a request file. To learn more, see Make outbound calls.

lk sip participant create [options] [REQUEST_FILE]

• REQUEST_FILE: A CreateSIPParticipantRequest as JSON.
• --trunk TRUNK_ID: Outbound trunk to use.
• --call NUMBER: Phone number or SIP user to call, not a full SIP URI.
• --number NUMBER: Phone number to call from. Defaults to a number on the trunk.
• --room NAME, -r NAME: Room to add the participant to.
• --identity ID, -i ID: Participant identity.
• --name NAME: Participant display name in the room.
• --display-name NAME: Display name in the SIP From header.
• --no-display-name: Send no display name, so the provider can do a CNAM lookup. Overrides --display-name.
• --wait: Wait for the callee to answer before returning.
• --timeout DURATION: How long the call rings before it fails. Default: 1m20s.
• --header KEY:VALUE: Custom SIP header for the INVITE. Repeatable.
• --media-enc, --codecs, --no-default-codecs: See Media options.

Examples

lk sip participant create \
  --trunk <trunk-id> \
  --call +14155550100 \
  --room my-sip-room \
  --identity sip-test \
  --wait

Place a call from a file:

{
  "sip_trunk_id": "<trunk-id>",
  "sip_call_to": "+14155550100",
  "room_name": "my-sip-room",
  "participant_identity": "sip-test"
}

lk sip participant create sip-participant.json --header "X-Customer-Id:1234"

Transfer

Transfer a SIP participant to another phone number or SIP endpoint. To learn more, see Call forwarding.

lk sip participant transfer --room NAME --identity ID --to DESTINATION [options]

• --room NAME, -r NAME: Room the participant is in. Required.
• --identity ID, -i ID: Identity of the participant to transfer. Required.
• --to DESTINATION: tel:<number> or sip:<user>@<host>. Required.
• --play-dialtone: Play a dial tone to the participant during the transfer.

Examples

lk sip participant transfer \
  --room my-sip-room \
  --identity sip-caller \
  --to tel:+15105550100 \
  --play-dialtone

Phone numbers

Use the lk number commands to manage LiveKit Phone Numbers.

lk number [command [command options]]

Search

Search for phone numbers available to purchase.

lk number search [options]

• --country-code CODE: Country to search, for example US. Required by the server.
• --area-code CODE: Area code to search, for example 415.
• --limit COUNT: Maximum number of results. Default: 50.
• --json, -j: Output as JSON. Default: false.

Examples

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

Purchase

Purchase one or more phone numbers.

lk number purchase --numbers NUMBER [options]

• --numbers NUMBER: Number to purchase, in E.164 format. Repeatable or comma-separated. Required.
• --sip-dispatch-rule-id RULE_ID: Dispatch rule to assign to the purchased numbers.
• --json, -j: Output as JSON.

Examples

lk number purchase \
  --numbers +14155550100,+14155550101 \
  --sip-dispatch-rule-id <dispatch-rule-id>

List

List the phone numbers in your project.

lk number list [options]

• --limit COUNT: Maximum results per page. Default: 50.
• --offset COUNT: Results to skip, for pagination. Default: 0.
• --status STATUS: Filter by active, pending, released, or offline. Repeatable. Default: active numbers, including offline ones.
• --sip-dispatch-rule-id RULE_ID: Filter by assigned dispatch rule.
• --json, -j: Output as JSON. Default: false.

Examples

lk number list --status active --status pending

Get

Show details for one phone number, including its status and dispatch rules. Set exactly one of --id or --number.

lk number get --id PHONE_NUMBER_ID
lk number get --number NUMBER

• --id PHONE_NUMBER_ID: Phone number ID.
• --number NUMBER: Phone number in E.164 format.
• --json, -j: Output as JSON.

Update

Assign a dispatch rule to a phone number. Set exactly one of --id or --number.

lk number update --id PHONE_NUMBER_ID --sip-dispatch-rule-id RULE_ID
lk number update --number NUMBER --sip-dispatch-rule-id RULE_ID

• --id PHONE_NUMBER_ID: Phone number ID.
• --number NUMBER: Phone number in E.164 format.
• --sip-dispatch-rule-id RULE_ID: Dispatch rule to assign.
• --json, -j: Output as JSON.

Release

Release one or more phone numbers from your project. Set exactly one of --ids or --numbers. For billing details, see Considerations.

lk number release --ids PHONE_NUMBER_ID
lk number release --numbers NUMBER

• --ids PHONE_NUMBER_ID: Phone number ID to release. Repeatable or comma-separated.
• --numbers NUMBER: Phone number to release, in E.164 format. Repeatable or comma-separated.

Examples

lk number release --numbers +14155550100