Skip to contentSkip to navigationSkip to topbar
Rate this page:
On 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

install-the-twilio-cli page anchor

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

macOSWindowsLinux

The suggested way to install twilio-cli on macOS is to use Homebrew(link takes you to an external page). If you don't already have it installed, visit the Homebrew site(link takes you to an external page) for installation instructions and then return here.

Once you have installed Homebrew, run the following command to install twilio-cli:


_10
brew tap twilio/brew && brew install twilio

(information)

Info

For other installation methods, see the Twilio CLI Quickstart.


Install the Serverless Plugin

install-the-serverless-plugin page anchor

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.


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


Create your Application using a Function Template

create-your-application-using-a-function-template page anchor

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.


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

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


_10
cd acme


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.


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

(information)

Info

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

initialize-your-environment page anchor

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

explore-your-application page anchor

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

register-a-demo-sip-user page anchor

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(link takes you to an external page) 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.

Making a SIP to SIP call

making-a-sip-to-sip-call page anchor

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.


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.


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


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

(information)

Info

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.

(information)

Info

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.

(warning)

Warning

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

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 theSIP section under Programmable Voice(link takes you to an external page) in your console.


Rate this page: