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!
The Twilio Command Line Interface, CLI, allows you to interact with the Twilio API from your terminal.
Once you have installed Homebrew, run the following command to install
brew tap twilio/brew && brew install twilio
The suggested way to install
twilio-cli is by using Scoop, a command-line installer for Windows. If you don’t already have it installed, visit the Scoop site for installation instructions and then return here.
Note PowerShell will need to be run as an administrator to avoid common permission issues when installing via Scoop.
- Add the
scoop bucket add twilio-scoop https://github.com/twilio/scoop-twilio-cli
- Install the app:
scoop install twilio
twilio-cli can be installed using the Advanced Package Tool (
apt) on most distributions such as Debian, Ubuntu, and Mint.
To do so, run the following commands in your terminal:
wget -qO- https://twilio-cli-prod.s3.amazonaws.com/twilio_pub.asc \ | sudo apt-key add - sudo touch /etc/apt/sources.list.d/twilio.list echo 'deb https://twilio-cli-prod.s3.amazonaws.com/apt/ /' \ | sudo tee /etc/apt/sources.list.d/twilio.list sudo apt update sudo apt install -y twilio
For other installation methods, see the Twilio CLI Quickstart.
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
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.
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.
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.
When you deployed your application, you were presented with a list of URLs.
- Open the URL that ends with /admin/index.html in your browser
- The password is
default(You can and should change this, we’ll do that later)
- 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.
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.
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.
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.
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.
Wire up another SIP client using another one of the user credentials we created. What about
After Bob is wired up,
alice can make a direct call to
bob on the same network.
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.
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.
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.
Now that you’ve seen things working, we’d like to invite you to explore how.
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.
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,
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.
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/outbound-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!
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.