Accepting incoming calls

A step-by-step guide to using an AI voice agent to accept incoming phone calls using LiveKit.

On this page

PrerequisitesStep 1: Set up environment variablesStep 2: Create an AI voice agentStep 3: Create an inbound LiveKit trunkAdd dispatch ruleStep 4: Call your agentNext steps
note

To make calls, see the Making outgoing calls quickstart.

This guide walks you through the steps to create an AI voice agent that responds to incoming calls. Users can call a phone number and interact directly with your AI-powered voice assistant. For example, your agent can be a resource in the following scenarios:

  • Call centers: Automate customer interactions and reduce wait times.
  • Customer service: Provide immediate assistance through an AI agent.
  • Sales inquiries: Allow customers to ask questions about products or services.

Prerequisites

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

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

tip

Log in to see your real credentials populated in many places throughout this page

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.
GitHubSlack
Sign in