Accepting incoming calls

This guide walks you through the following steps to create an AI voice agent that responds to incoming calls:

• Creating a voice agent using the LiveKit Agents framework.
• Setting up an inbound LiveKit trunk.
• Adding a dispatch rule to place callers in rooms.

Prerequisites

The following are required to complete the steps in this quickstart:

• A phone number purchased from your SIP trunk provider.
• A SIP trunk with your provider.
• LiveKit CLI installed.
• SIP server: LiveKit Cloud or a self-hosted SIP server.

Instructions for setting up a SIP trunk with Twilio or Telnyx are available in the Create and configure SIP trunk quickstart.

Step 1: Set up environment variables

Set up the following environment variables to configure the LiveKit CLI to use your LiveKit Cloud or self-hosted LiveKit server instance:

export LIVEKIT_URL=<your LiveKit server URL>
export LIVEKIT_API_KEY=<your API Key>
export LIVEKIT_API_SECRET=<your API Secret>

Step 2: Create an AI voice agent

The fastest way to create an agent is by using the LiveKit CLI:

lk app create --template voice-pipeline-agent-python

• Enter your API keys at the prompts. Alternatively, you can skip the prompts and manually edit the .env.local file with your API keys.

• Follow the instructions in the command output to start your agent.

Step 3: Create an inbound LiveKit trunk

An inbound SIP trunk instructs LiveKit to accept calls to one or more numbers that you own. Create a file inbound-trunk.json with the following content. This example assumes +15105550100 is the phone number and that the provider trunk is configured with username and password authentication:

{
  "trunk": {
    "name": "Twilio inbound trunk",
    "numbers": ["+15105550100"],
    "auth_username": "<username>",
    "auth_password": "<password>"

  }
}

Create the LiveKit inbound SIP trunk using the CLI:

lk sip inbound create inbound-trunk.json

The output includes the LiveKit trunk ID:

SIPTrunkID: <livekit_trunk_id>

Add dispatch rule

Dispatch rules route inbound SIP calls into LiveKit rooms. The dispatchRuleIndividual rule in this example, routes each caller into an individual room with the agent. The name of the room is prefixed with call:

Create dispatch-rule.json file:

{
  "name": "My dispatch rule",
  "trunk_ids": ["<livekit_trunk_id>"],
  "rule": {
    "dispatchRuleIndividual": {
      "roomPrefix": "call"
    }
  }
}

Apply the dispatch rule for the trunk using the CLI:

lk sip dispatch create dispatch-rule.json

Step 4: Call your agent

Calling the phone number you assigned to the LiveKit trunk places you in a room named my-sip-room. After you join the room, your agent is dispatched to the room and you can talk to your agent.

Next steps

• Using SIP participant attributes: Modify the agent you created in Step 2 based on a caller's attributes.

• To learn more, see the following topics:

  • Dispatch rules: You can create dispatch rules to control how callers are dispatched to rooms, configure authentication, and add participant attributes.
  • SIP participant: You can manage SIP participants like any other LiveKit participant. You can also use SIP specific attributes to manage callers based on the number they call or the number they're calling from, and more.