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.
The suggested way to install twilio-cli on macOS is to use Homebrew. If you don't already have it installed, visit the Homebrew site for installation instructions and then return here.
Once you have installed Homebrew, run the following command to install twilio-cli:
brew tap twilio/brew && brew install 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.
1cd acme2
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.
When you deployed your application, you were presented with a list of URLs.
default (You can and should change this, we'll do that later)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 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.
ADMIN_PASSWORD=12345
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.
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 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.
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 in your console.