Menu

Expand
Rate this page:

SIP Quickstart

SIP, or Session Initiation Protocol, is a powerful connectivity tool in the telephony world. The protocol allows for initiating, terminating, and modifying user sessions over an IP network. A common use case of SIP is VoIP, or Voice Over IP applications.

Twilio provides the ability to create a SIP Domain, or commonly referred to as a SIP Interface, that will allow multiple SIP clients to not only register, but also connect with each other, as well as, route out to the traditional public switched telephone network (PSTN).

When you have completed this Quickstart, you’ll have a registered SIP Domain, complete with auto-generated demo users, and scalable enterprise level functionality that supports inbound and outbound calling. There is even a prebuilt IVR (Interactive Voice Response) that maps your SIP clients to an extension that will help demonstrate the power of Twilio’s Programmable Voice platform.

The new normal of remote work has made this solution more critical than ever. This project will show how to set up your remote workers for success.

Let’s get started!

Install the Twilio CLI

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

One of the easiest ways to install the CLI on Mac OS X is to use Homebrew. If you don't already have it installed, visit the Homebrew site for installation instructions and then return here.

Once Homebrew is installed, simply run the following command to install the CLI:

brew tap twilio/brew && brew install twilio

Updating

If you already installed the CLI with brew and want to upgrade to the latest version, run:

brew upgrade twilio

Warning for Node.js developers

If you have installed Node.js version 10.12 or higher on your Mac, you can avoid potential Node.js version conflicts by installing the CLI using npm:

npm install twilio-cli -g

Before we can install, we need to make sure you have Node.js installed (version 10.12 or above). To see if you have node installed, try running this command:

node -v

If your system reports v10.12.0 or above, you can skip the next step.

Installing Node.js on Windows

Using the Windows Installer (.msi) is the recommended way to install Node.js on Windows. You can download the installer from the Node.js download page.

Installing Twilio CLI

The CLI is installed with npm (Node Package Manager), which comes with Node.js. To install the CLI run the following command:

npm install twilio-cli -g

Note the -g option is what installs the command globally so you can run it from anywhere in your system.

Updating

If you already installed the CLI with npm and want to upgrade to the latest version, run:

npm install twilio-cli@latest -g

Before we can install, we need to make sure you have Node.js installed (version 10.12 or above). Even if you already installed Node yourself, the CLI works best when you install it using nvm. Here's how to get nvm installed on most Linux systems:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

Please visit the nvm installation instructions for additional options and troubleshooting steps. Once you have nvm installed, run the following to install and use the most recent LTS release of Node.js:

nvm install --lts
nvm use <insert version reported from above>

Installing other Twilio CLI prerequisites for Linux

Depending on your distribution, you will need to run one of the following commands:

  • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
  • Red Hat-based: sudo yum install libsecret-devel
  • Arch Linux: sudo pacman -S libsecret

Installing Twilio CLI

The CLI is installed with npm (Node Package Manager), which comes with Node.js. To install the CLI run the following command:

npm install twilio-cli -g

Note the -g option is what installs the command globally so you can run it from anywhere in your system.

Updating

If you already installed the CLI with npm and want to upgrade to the latest version, run:

npm install twilio-cli@latest -g

Install the Serverless Plugin

The Twilio CLI supports plugins, which give you additional control and superpowers. We’re going to install the serverless plugin which allows you to seamlessly deploy functions from your local machine.

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

Create your Application using a Function Template

The serverless plugin allows you to initialize an application from a template. The template we are going to use has everything we 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!

We’ll take a look in more detail after we get things up and running. But for now, let’s create our app!

In this example I am going to name the project the same name as my company, Acme. Feel free to replace it with your company name.

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

This will create a new folder named acme that will contain all of our code.

cd acme

Deploy your application

The serverless plugin allows you to deploy code from your local machine to the Twilio Serverless platform. Once deployed your application will be hosted at a publicly accessible URL.

twilio serverless:deploy

This command will create a Service for you that will house your hosted development environment. The command will output all the functions and assets that have been deployed to your dev environment.

Note that the URLs are unique to your instance. This will create a new Serverless service and a new development environment.

We understand that you might want to know what is being deployed to your account before doing so. If you want to, you can jump down to the Learn More section to learn more about what functions will be deployed to your account.

You should run this command whenever you want to make changes to your hosted live development environment.

Initialize your environment

When you deployed your application, you were presented with a list of URLs.

  1. Open the URL that ends with /admin/index.html in your browser
  2. The password is default (You can and should change this, we’ll do that later)
  3. Click the button to Initialize your environment

The initialization process will create the necessary tools to make your SIP Domain work with some demo users, and a dial in number. You definitely could’ve done this all yourself, but this is a quickstart, and we want you to get started quickly ;)

This page will now host a checklist that will validate that your environment is working properly. It also provides handy links to get to the items that were automatically initialized for you.

You should note that there is a failing check, and that’s because we haven’t yet changed the default password. We’ll do that here shortly, but first let’s explore the application.

Explore your application

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.

Register a demo SIP User

We are now ready to register a SIP client with your domain. You’ll notice on this page there is a list of users and their registration SIP Domain. The password by default is the same for all default users, and it is available on the admin page.

There are several free softphone clients, and we recommend using Zoiper to connect your SIP account.

Placing Outbound calls

If you wire up the user alice to your SIP client, you should be able to make an outgoing call to the PSTN (Public Switch Telephone Network). Go ahead and place a call to your phone number. When your phone rings, it will be coming from the caller id specified.

Incoming Calls

You should also be able to call the incoming number from any telephone. When the call is answered, you will be prompted to enter an extension. Enter 100 and you will be connected to the alice SIP Client.

Pretty neat right? We’ll explore this code in a bit.

Making a SIP to SIP call

Wire up another SIP client using another one of the user credentials we created. What about bob?

After Bob is wired up, alice can make a direct call to bob on the same network.

Modify your application

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

There is an entry for ADMIN_PASSWORD, change that to something other than default.

ADMIN_PASSWORD=12345

Obviously, though, don’t use that password (that’s the same one as my luggage 😉.)

Now make sure your file is saved and then deploy.

twilio serverless:deploy

After it's deployed revisit your hosted /admin/index.html page, use your new password, and you will see that your checks are now all green.

Anytime you make a change to your example application, remember to save and re-deploy your application.

Learn more

Now that you’ve seen things working, we’d like to invite you to explore how.

Extensions file

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

This file’s extension contains .private.js, which for the Serverless plugin, means it will not be served publicly, but can be accessed by other functions.

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

If you do make a change to this file, make sure to navigate to your hosted /admin/index.html and create the additional users automatically.

Dial by extension menu

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 will gather digits from the user, and then submit them back to the function which can be found using the event.Digits value. Notice that the number of digits, numDigits, has been limited to 3, because that’s the length of each of our extensions, 100, 200, etc. are only 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 is wired up to a number that was chosen during initialization, if you want to change this number, head over to the hosted admin/index.html and choose a new number by pressing the button. You’ll see that the chosen number has the “When a Call Comes In” value set to this Function <YOUR HOSTED SERVICE PREFIX>/extension-menu.

Outbound calls

When an outgoing call is placed from a SIP Device something needs to handle it, and your SIP Domain is responsible to define what happens. We’ve wired this up to the SIP Domain using the Function functions/outgoing-calls.js

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. Please explore and feel free to make it behave however you’d like. Remember to re-deploy!

Everything else

During initialization, a SIP Domain was created and a set of demo credentials were created and added to a new credential list. The SIP Domain was set up to allow for registration, and the credential list was used for allowing registrants. This was all done by making use of the SIP API.

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

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more