SIP Quickstart

Approximately 20-30 minutes

Before you begin, make sure you have the following:

• A Twilio account.
• A Twilio phone number with Voice capabilities.
• Node.js installed (version 14 or higher) on your local machine.
• A SIP softphone client such as Zoiper or Linphone.
• Basic familiarity with your terminal or command line interface.

A softphone is a software application that lets you make voice calls over the internet using your computer or mobile device instead of a traditional phone. Softphones connect to SIP servers so you can make and receive calls through your SIP account.

The Twilio Command Line Interface, CLI, allows you to interact with the Twilio API from your terminal.

brew tap twilio/brew && brew install twilio

1
wget -qO- https://twilio-cli-prod.s3.amazonaws.com/twilio_pub.asc \
2
  | sudo apt-key add -
3
sudo touch /etc/apt/sources.list.d/twilio.list
4
echo 'deb https://twilio-cli-prod.s3.amazonaws.com/apt/ /' \
5
  | sudo tee /etc/apt/sources.list.d/twilio.list
6
sudo apt update
7
sudo apt install -y twilio

The Twilio CLI supports plugins, which give you additional control and superpowers. Install the serverless plugin to deploy functions from your local machine.

twilio plugins:install @twilio-labs/plugin-serverless

The serverless plugin initializes an application from a template. The template includes everything you need: the ability to create and register a SIP domain, with demo users, a function that hosts an IVR (Interactive Voice Response) system to route calls to SIP users by extension, a splash page, and much more!

You'll examine the details after the application runs. For now, create your app.

This example names the project the same as the company, acme. If you want to name your project something else, replace acme in the commands below with your desired project name.

twilio serverless:init acme --template="sip-quickstart"

If the command runs successfully, it will look like the following:

1
✔ Creating project directories and files
2
✔ Configuring Environment Variables in .env
3
✔ Saving README to /path/to/your/project/acme/readmes/sip-quickstart.md
4
✔ Installing Dependencies
5
✔ Creating asset: actions.private.js
6
✔ Creating asset: admin-client.js
7
✔ Creating asset: admin.css
8
✔ Creating asset: index.html
9
✔ Creating asset: shared.private.js
10
✔ Creating asset: statuses.private.js
11
✔ Creating asset: extensions.private.js
12
✔ Creating asset: index.html
13
✔ Creating asset: site.css
14
✔ Creating function: admin/check-status.js
15
✔ Creating function: admin/login.js
16
✔ Creating function: admin/perform-action.js
17
✔ Creating function: extension-menu.js
18
✔ Creating function: outbound-calls.js
19
✔ Creating function: sip-configuration.js
20
INFO Make sure to configure APP_NAME,ADMIN_PASSWORD,DEFAULT_SIP_USER_PASSWORD in the .env file
21
SUCCESS Downloaded new template into the "" subdirectories.
22
Check readmes/sip-quickstart.md for template instructions.
23
✔ Downloading template: "sip-quickstart"
24
✔ Downloading .gitignore file
25
✔ Installing dependencies
26
╭──────────────────────────────────────────────────────────────────────────────╮
27
│                                                                              │
28
│   Success!                                                                   │
29
│                                                                              │
30
│   Created acme at /path/to/your/project                                      │
31
│                                                                              │
32
│   Inside that directory, you can run the following command:                  │
33
│                                                                              │
34
│   npm start                                                                  │
35
│     Serves all functions in the ./functions subdirectory and assets in the   │
36
│     ./assets directory                                                       │
37
│                                                                              │
38
│   Get started by running:                                                    │
39
│                                                                              │
40
│   cd acme                                                                    │
41
│   npm start                                                                  │
42
│                                                                              │
43
╰──────────────────────────────────────────────────────────────────────────────╯

This creates a new folder named acme that contains all of your code.

cd acme

The serverless plugin deploys code from your local machine to the Twilio Serverless platform. Once deployed, your application runs at a publicly accessible URL.

twilio serverless:deploy

This command creates a Service that houses your hosted development environment. The command outputs all the functions and assets deployed to your dev environment.

Run this command whenever you want to make changes to your hosted live development environment.

Follow these steps to complete the setup of your SIP Domain with demo users:

When you deployed your application, the output presented a list of URLs. Find the URL that ends with /admin/index.html.

1. Open the URL in your browser - it will look like: https://your-service-name.twil.io/admin/index.html
2. You'll see a password prompt asking you to log in

1. Enter the password: default (this is the initial ADMIN_PASSWORD from your .env file)
2. Click Let me in to access the admin interface

After you log in, a message will say the following: The SIP Quickstart requires that you set up a few things on your account

1. Click the button that says Initialize your application for your environment
2. Wait for initialization to complete - this process creates:
   • A SIP Domain.
   • Three demo SIP credentials (alice, bob, charlie).
   • A credential list.
   • Necessary configurations for your SIP setup.
3. The page refreshes and displays a Configuration Checklist.

After initialization completes, the admin interface displays a Configuration Checklist with status indicators showing:

• SIP Domain is created.
• Credential List contains 3 accounts (alice, bob, charlie).
• The default password for the SIP credentials (e.g., ThisIs1Password!).
• Your incoming phone number.
• Links to the automatically initialized resources.

Note: There is a failing check for the admin password, since you haven't yet changed it from the default. You'll fix that later.

There is a splash page that you can now share with your team up and running at /index.html. Open that up in a browser.

This page displays your call in number and your outgoing caller id. Both of these values can be changed on the previous admin page.

You can now register a SIP client with your domain. On this page you'll find a list of users and their registration SIP Domain. By default, the password is the same for all default users and appears on the admin page.

Now let's configure a softphone client to register with your SIP Domain. You can configure all three demo users (alice, bob, charlie) on separate devices or softphone instances.

For the first user (Alice):

1. Download and install your chosen softphone client. This tutorial uses Zoiper.
2. Open the softphone and select the option to add a new SIP account.
3. Enter the SIP credentials:
   • Username: alice
   • Password: The default SIP user password shown on your admin page (for example, ThisIs1Password!)
   • Domain/Server: The SIP Domain shown on the splash page (it looks like your-service-name.sip.us1.twilio.com)
   • Transport: UDP or TCP (either works)
4. Save the configuration and the softphone will attempt to register with your SIP Domain
5. Verify registration: You should see a status indicating "Registered" or "Connected"

For additional users (Bob and Charlie):

Repeat the same process on other devices or softphone instances, using these credentials:

• Bob: Username bob, Password from admin page, Extension 200
• Charlie: Username charlie, Password from admin page, Extension 300

Once your softphone registers, you can make and receive calls through your Twilio SIP Domain.

Now that you have a softphone configured with your first demo user (for example, alice), let's test the different calling capabilities.

With your softphone registered and connected:

1. Open your softphone client (the one you just configured with the alice credentials).
2. Dial any phone number using your softphone (for example, your mobile phone number).
3. Press the call button in your softphone to initiate the call.
4. Answer the call on your mobile phone - you should see the caller ID that was specified on the admin page.

This demonstrates that your SIP client places calls to the PSTN (Public Switched Telephone Network) through Twilio.

Test receiving calls through your SIP extension:

1. From any telephone, call the incoming phone number displayed on your splash page (/index.html).
2. Wait for the IVR - you'll hear a prompt asking you to enter an extension.
3. Enter extension 100 (which corresponds to the alice user).
4. Your softphone will ring - answer the call on your softphone to connect.

This shows how the dial-by-extension menu routes incoming calls to your registered SIP clients.

1
const dial = twiml.dial({
2
  timeout: 30,
3
  action: './extension-menu'
4
});
5
dial.sip(`sip:${username}@${regionalDomainName}`);

1
if (event.DialCallStatus && event.DialCallStatus !== 'completed') {
2
  twiml.say('The extension is unavailable');
3
  twiml.redirect('./extension-menu');
4
  return callback(null, twiml);
5
}

To test direct SIP to SIP calling between extensions, you'll need at least two registered users:

1. Set up a second softphone on another device or computer (or use a second softphone instance).
2. Register this softphone using different demo user credentials (for example, bob) - follow the same connection steps from the "Connect your SIP account" section above.
3. Verify both clients are registered - both should show "Registered" or "Connected" status.
4. From the first softphone (registered as alice), dial the extension number for the other user:
   • To call Bob: dial 200.
   • To call Charlie: dial 300.
5. The second softphone (registered as bob) should ring.
6. Answer on the second softphone to establish a direct SIP to SIP call.

Extension reference:

• Alice: Extension 100
• Bob: Extension 200
• Charlie: Extension 300

This demonstrates peer-to-peer calling between SIP clients registered to the same domain, without routing through the PSTN.

You should definitely change that admin password. On your local machine edit the file .env.

Find the entry for ADMIN_PASSWORD and change it to something other than default.

ADMIN_PASSWORD=your_secure_password_here

Now make sure your file is saved and then deploy.

twilio serverless:deploy

After deployment, revisit your hosted /admin/index.html page, use your new password, and view your all-green checks.

Now that you've seen things working, you can explore how to further modify and extend this application to suit your needs.

Head over to your local project directory and checkout assets/extensions.private.js.

You'll notice that the demo users have all been added here. You can also add your own users here by following the same sort of format.

Navigate to the function file located in functions/extension-menu.js. This Twilio Function uses the extensions file to create a menu that performs SIP dialing based on input from the caller.

The code makes heavy use of the <Gather> TwiML verb, which gathers digits from the user, then submits them back to the function via the event.Digits value. The numDigits parameter is set to 3 because each extension (100, 200, etc.) contains three digits.

Feel free to explore and modify this file, it's all yours! Just remember you need to deploy it to see changes.

This function connects to a number chosen during initialization. To change this number, open the hosted /admin/index.html and select a new number by pressing the button. The chosen number has its "When a Call Comes In" value set to this Function <YOUR HOSTED SERVICE PREFIX>/extension-menu.

When you place an outgoing call from a SIP Device, your SIP Domain defines what happens. The Function functions/outbound-calls.js connects to the SIP Domain to handle this.

This function attempts to extract a number and then places a call to the PSTN, setting the callerId attribute on <Dial> TwiML verb. The Caller ID can be changed on your hosted /admin/index.html.

It's important to note too that this function is completely programmable. Explore and feel free to make it behave however you'd like. Remember to re-deploy!

During initialization, the system created a SIP Domain and added demo credentials to a new credential list. The SIP Domain enables registration, and the credential list manages registrants. The SIP API handles all of these operations.

You can locate this information on your hosted Admin page /admin/index.html or in the SIP section under Programmable Voice in your console.

Now that you have a working SIP infrastructure, explore these resources to expand your implementation:

• SIP Overview - Learn more about Twilio's SIP capabilities.
• TwiML Voice: Dial - Deep dive into the Dial verb and its parameters.
• SIP Interface API - Complete API reference for managing SIP domains programmatically.
• Twilio Functions - Learn more about serverless functions.
• SIP Trunking - Connect your existing phone system to Twilio.