Twilio Voice integration | LiveKit Documentation

Inbound calls with Twilio programmable voice

Accept inbound calls using Twilio programmable voice. You need an inbound trunk and a dispatch rule created using the LiveKit CLI (or SDK) to accept calls and route callers to LiveKit rooms. The following steps guide you through the process.

Unsupported features

This method doesn't support SIP REFER or outbound calls. To use these features, switch to Elastic SIP Trunking. For details, see the Configuring Twilio SIP trunks quickstart.

Step 1. Purchase a phone number from Twilio

If you don't already have a phone number, see How to Search for and Buy a Twilio Phone Number From Console.

Step 2. Set up a TwiML Bin

Other approaches

This guide uses TwiML Bins, but you can also return TwiML via another mechanism, such as a webhook.

TwiML Bins are a simple way to test TwiML responses. Use a TwiML Bin to redirect an inbound call to LiveKit.

To create a TwiML Bin, follow these steps:

Navigate to your TwiML Bins page.

Create a TwiML Bin and add the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Sip username="<sip_trunk_username>" password="<sip_trunk_password>">
      sip:<your_phone_number>@<your SIP endpoint>;transport=tcp
    </Sip>
  </Dial>
</Response>

Step 3. Direct phone number to the TwiML Bin

Configure incoming calls to a specific phone number to use the TwiML Bin you just created:

Navigate to the Manage numbers page and select the purchased phone number.
In the Voice Configuration section, edit the A call comes in fields. After you select TwiML Bin, select the TwiML Bin created in the previous step.

Step 4. Create a LiveKit inbound trunk

Use the LiveKit CLI to create an inbound trunk for the purchased phone number.

Create an inbound-trunk.json file with the following contents. Replace the phone number and add a username and password of your choosing:
```
{
  "trunk": {
    "name": "My inbound trunk",
    "numbers": ["<your_phone_number>"],
    "authUsername": "<sip_trunk_username>",
    "authPassword": "<sip_trunk_password>"
  }
}
```
Note
Be sure to use the same phone number, username, and password that's specified in the TwiML Bin.

Use the CLI to create an inbound trunk:

lk sip inbound create inbound-trunk.json

Step 5. Create a dispatch rule to place each caller into their own room.

Use the LiveKit CLI to create a dispatch rule that places each caller into individual rooms named with the prefix call.

Create a dispatch-rule.json file with the following contents:

{
  "dispatch_rule":
   {
     "rule": {
       "dispatchRuleIndividual": {
         "roomPrefix": "call-"
       }
     }
   }
}

Create the dispatch rule using the CLI:
```
lk sip dispatch create dispatch-rule.json
```
If you already have a default caller dispatch rule and want to match a specific trunk, create the dispatch rule using the trunks flag with the ID of the trunk you just created:
```
lk sip dispatch create dispatch-rule.json --trunks "<trunk-id>"
```

Testing with an agent

Follow the Voice AI quickstart to create an agent that responds to incoming calls. Add the prebuilt EndCallTool to your agent's tools so the agent can hang up the call when the conversation is complete (Python only). For Node.js or a custom implementation, see Hang up. Then call the phone number and your agent should pick up the call.

Multi-number routing

To route calls from different phone numbers to different agents (for example, one number for English support and another for Spanish), create a separate inbound trunk and dispatch rule for each number.

Step 1. Set up a TwiML Bin for each number

Create a TwiML Bin for each phone number. Each TwiML Bin uses the same LiveKit SIP host but includes the specific phone number in the SIP URI:

Note

Use different credentials for each trunk so LiveKit can identify which trunk a call belongs to.

English number TwiML Bin:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Sip username="<english_trunk_username>" password="<english_trunk_password>">
      sip:<english_phone_number>@<your SIP endpoint>;transport=tcp
    </Sip>
  </Dial>
</Response>

Spanish number TwiML Bin:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Sip username="<spanish_trunk_username>" password="<spanish_trunk_password>">
      sip:<spanish_phone_number>@<your SIP endpoint>;transport=tcp
    </Sip>
  </Dial>
</Response>

Direct each Twilio phone number to its corresponding TwiML Bin.

Step 2. Create a LiveKit inbound trunk for each number

Create an inbound trunk for each phone number. Use the credentials from the corresponding TwiML Bin:

english-trunk.json:

{
  "trunk": {
    "name": "English support trunk",
    "numbers": ["<english_phone_number>"],
    "authUsername": "<english_trunk_username>",
    "authPassword": "<english_trunk_password>"
  }
}

spanish-trunk.json:

{
  "trunk": {
    "name": "Spanish support trunk",
    "numbers": ["<spanish_phone_number>"],
    "authUsername": "<spanish_trunk_username>",
    "authPassword": "<spanish_trunk_password>"
  }
}

Create both trunks using the CLI:

lk sip inbound create english-trunk.json
lk sip inbound create spanish-trunk.json

Note the trunk IDs returned by each command.

Step 3. Create a dispatch rule for each trunk

Create a dispatch rule for each trunk. Use the trunks flag to bind each rule to a specific trunk, and use roomConfig to dispatch a different agent for each number:

english-dispatch.json:

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleIndividual": {
        "roomPrefix": "english-"
      }
    },
    "name": "English dispatch rule",
    "roomConfig": {
      "agents": [{
        "agentName": "english-agent"
      }]
    }
  }
}

spanish-dispatch.json:

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleIndividual": {
        "roomPrefix": "spanish-"
      }
    },
    "name": "Spanish dispatch rule",
    "roomConfig": {
      "agents": [{
        "agentName": "spanish-agent"
      }]
    }
  }
}

Create both dispatch rules with their corresponding trunk IDs:

lk sip dispatch create english-dispatch.json --trunks "<english-trunk-id>"
lk sip dispatch create spanish-dispatch.json --trunks "<spanish-trunk-id>"

Now calls to the English number route to the english-agent and calls to the Spanish number route to the spanish-agent.

Connecting to a Twilio phone conference

You can bridge Twilio conferencing to LiveKit via SIP, allowing you to add agents and other LiveKit clients to an existing Twilio conference. This requires the following setup:

The example in this section uses Node and the Twilio Node SDK.

Step 1. Set Twilio environment variables

You can find these values in your Twilio Console:

export TWILIO_ACCOUNT_SID=<twilio_account_sid>
export TWILIO_AUTH_TOKEN=<twilio_auth_token>

Step 2. Bridge a Twilio conference and LiveKit SIP

Create a bridge.js file and update the twilioPhoneNumber, conferenceSid, sipHost, and from field for the API call in the following code:

Note

If you're signed in to LiveKit Cloud, your sip host is filled in below.

import twilio from 'twilio';

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

const twilioClient = twilio(accountSid, authToken);

/**
 * Phone number bought from Twilio that is associated with a LiveKit trunk.
 * For example, +14155550100.
 * See https://docs.livekit.io/sip/quickstarts/configuring-twilio-trunk/
 */
const twilioPhoneNumber = '<sip_trunk_phone_number>';

/**
 * SIP host is available in your LiveKit Cloud project settings.
 * This is your project domain without the leading "sip:".
 */
const sipHost = '<your SIP endpoint>';

/**
 * The conference SID from Twilio that you want to add the agent to. You
 * likely want to obtain this from your conference status callback webhook handler.
 * The from field must contain the phone number, client identifier, or username
 * portion of the SIP address that made this call.
 * See https://www.twilio.com/docs/voice/api/conference-participant-resource#request-body-parameters
 */
const conferenceSid = '<twilio_conference_sid>';
await twilioClient.conferences(conferenceSid).participants.create({
    from: '<valid_from_value>',
    to: `sip:${twilioPhoneNumber}@${sipHost};transport=tcp`,
});

Step 3. Execute the file

When you run the file, it bridges the Twilio conference to a new LiveKit session using the previously configured dispatch rule. This allows you to automatically dispatch an agent to the Twilio conference.

node bridge.js