Inbound calls with Twilio Voice

Inbound calls with Twilio programmable voice

Accept inbound calls using Twilio programmable voice. All you need is 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.

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

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:

1. Navigate to your TwiML Bins page.

2. 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 host>
       </Sip>
     </Dial>
   </Response>

   Copy

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:

1. Navigate to the Manage numbers page and select the purchased phone number.

2. 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.

1. 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",
       "auth_username": "<sip_trunk_username>",
       "auth_password": "<sip_trunk_password>"
     }
   }

   Copy
   Note

   Be sure to use the same username and password that's specified in the TwiML Bin.

2. Use the CLI to create an inbound trunk:

   lk sip inbound create inbound-trunk.json

   Copy

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.

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

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

   Copy

Testing with an agent

You can test your setup by creating a MultimodalAgent to respond to incoming calls.

1. Use the CLI to create an Node.js multimodal agent:

   lk app create --template=multimodal-agent-node

   Copy

   Follow the instructions in the command output to start the agent:

   cd /path/to/your_app
   pnpm install
   pnpm build
   node dist/agent.js dev

   Copy

2. Call the phone number and an agent picks up the call.

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:

• Twilio conferencing.
• LiveKit inbound trunk.
• LiveKit agent that responds to calls.

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:

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 host>';

/**
 * 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