Quickly Enable Your Employees to Work from Home Using Twilio Programmable Voice

Enable employees to work from h ome

If your PBX solution does not natively allow for remote working and you need to act fast, this solution is for you. This tutorial shows you how to create a solution with Twilio Programmable Voice and softphone software that enables employees to work from their homes.

Configure the Programmable Voice SIP Endpoint

You can forward incoming calls to Twilio numbers registered to SIP endpoints, and use a free softphone as an endpoint while working from home, as shown below:

Flow for how employees can work from home using Twilio

To get started with the project you will need the following:

A Twilio account. Sign up for a free trial account and get a $10 credit.
A call-enabled Twilio Phone Number.
SIP endpoint (IP Phones (e.g. Obihai) or Softphones (e.g. Zoiper or X-Lite)).

Create the application

Go to twilio.com and sign up for a free account or log in to your existing account.

If you don't currently own a Twilio phone number with Voice functionality, you'll need to purchase one. Navigate to the Buy a Number page, check the "Voice" box and click "Search."

Choose Voice-enabled when buying a phone number

You’ll then see a list of available phone numbers and their capabilities. Find a number that you like and click "Buy" to add it to your account.

Select a number with voice capabilities.

In this solution, we will need to buy a unique number for each employee you want to forward calls to.

The next step is to create a TwiML bin to allow the remote worker to place outbound calls.

Go to TwiML Bins on Console:

Create a TwiML Bin.

Select the “+” and create a TwiML bin for our outbound calls.

Populate the TwiML Bin with the code.

TwiML Bins have some built in mustache templates, such as {{To}}, {{From}}, {{#e164}} and others. You can find out more in How To use templates with TwiML Bins.

Give the TwiML Bin a friendly name like ‘TwilioSipDemoOutbound’. Paste in the TwiML below (replacing the existing content):

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial answerOnBridge="true" callerId="{{#e164}}{{From}}{{/e164}}">{{#e164}}{{To}}{{/e164}}</Dial>
</Response>

At the bottom of the edit box, it should say: ‘Valid Voice TwiML’ if everything went well. Click the ‘Create’ Button and scroll to the top and copy the URL to your Clipboard (or click the copy icon).

It should be something similar to this: https://handler.twilio.com/twiml/EHxxxxxxxxxxxxxxxxx

Save this link for when we create our SIP Domain next.

Go back to the TwiML Bin page and click on the “+” again. Give the TwiML Bin a friendly name like ‘TwilioSIPDemo_1_your number’, in this example we used ‘TwilioSIPDemo_18068535535’.

Paste in the TwiML below (replacing the existing content):

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial timeout="20">
        <Sip> username@yourdomain.sip.us1.twilio.com</Sip>
    </Dial>
</Response>

In our example we used:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial timeout="20">
        <Sip> 18068535535@twiliosipdemo.sip.us1.twilio.com</Sip>
    </Dial>
</Response>

Modify the TwiML Bin.

At the bottom of the edit box, it should say: ‘Valid Voice TwiML’ if everything went well. Click the ‘Create’ Button.

Associate the TwiML Bin to the number you purchased. Go to your Active Numbers and under the Voice & Fax, “A CALL COMES IN”, select the TwiML bin we just created:

Set up your webhook for voice calls.

Click the red "Save" button.

For each employee, you will need to create separate TwiML bins for inbound calls and associate to their Twilio numbers.

The next step is to create a SIP domain for your account. A SIP Domain resource describes a custom DNS hostname that can accept SIP traffic for your account.

Think about this as your address for calls to reach you on the public telephone network. In VoIP (voice over IP), a SIP URI serves as your global unique address, similar to a phone number in the PSTN (public switched telephone network). We will need this to configure the softphones to register to your Twilio account.

Go to the SIP domains page.

Go to the Voice SIP Domains. In this example, we will create the domain twiliosipdemo.sip.us1.twilio.com - you will need to specify the “twiliosipdemo” this way. You should see a screen like this one:

Select “Create new SIP Domain”.

Under Properties - type a FRIENDLY NAME - in our case we used “Twilio SIP Demo”

For the SIP URI field - type "twiliosipdemo” - this will create the SIP Domain “twiliosipdemo.sip.us1.twilio.com”.

Update the SIP URI field.

Under Voice Configuration, on the REQUEST URL - enter the URL from your TwiML ‘TwilioSipDemoOutbound’ link:

Update the Request URI field.

Under Voice Authentication, click on the “+” sign and add an IP ACCESS CONTROL LIST. This is optional, but it is recommended for extra security.

Update the IP Access Control List.

Create a new Access Control List which contains a list of IP Addresses resources that can access to your SIP Domain. Requests to your SIP Domain from an IP address that is not in the ACL will be blocked.

Create a new access control list.

xx.xx.xx.xx is the IP address range of your SIP clients.

Check with your employees which IP addresses their Service Provider assigned to them (e.g. 47.31.34.10/32). For each employee, you will need to add their IP addresses to this Access List.

Click on the “+” for CREDENTIAL LIST. Create a new SIP Credential List resource, which contains the credentials of the employees who are allowed to reach your SIP Domain. Twilio will only allow traffic from employees who have their credentials in the credential list.

Update the control list.

In this example, we used for the first employee username "18068535535" and password "Twiliosipdemo123".

Update Voice Authentication ACLs.

For each employee, you will need to create separate usernames and passwords. And add to the CREDENTIAL LISTS. For example:

Update Voice Authentication credential lists.

Under SIP REGISTRATION, make sure you turn SIP Registration to ENABLED and add your Credential Lists as well.

Update credential lists on SIP registration.

Your new SIP DOMAIN should look like this:

Check that your SIP domain is configured properly.

Hit the Save button.

Connect a softphone to our Twilio SIP endpoint

Next, we need to configure your SIP endpoint. This can vary depending on which end point you chose. There are many options available, softphones or IP phones.

A softphone is an application that runs installed on a computer or and uses the internet to make calls. In this tutorial, we are using Zoiper’s softphone, which you can download here, but this configuration should work with any softphone of your choice.

Download the Zoiper’s softphone, install and you will be prompted to add a username and password. This is the same username and password we used in your Twilio Credential Lists (username: 18068535535 / password: Twiliosipdemo123).

Install Zoiper.

Hit “Login” instead of “Create account”. On the hostname, copy and paste the SIP Domain we just created: twiliosipdemo.sip.us1.twilio.com

Fill in the SIP hostname.

Hit “Next” and “Skip” on the next screen, then “Yes” on the warning.

Click "Yes" button on warning screen.

Select “configure” and test your audio and microphone. On the configuration for the SIP account, select “Advanced” to see the “Caller ID Name” field. Enter the Twilio number for that user. In our example it is “18068535535”.

You should see your client registered correctly like this:

Update SIP credentials in Zoiper.

In case you do not see the green checkmark, follow these troubleshooting steps:

First, check connectivity to the internet, for example:

youruser$ ping  twiliosipdemo.sip.us1.twilio.com
PING twiliosipdemo.sip.us1.twilio.com (54.172.60.0): 56 data bytes
64 bytes from 54.172.60.0: icmp_seq=0 ttl=253 time=41.487 ms
64 bytes from 54.172.60.0: icmp_seq=1 ttl=253 time=41.971 ms
64 bytes from 54.172.60.0: icmp_seq=2 ttl=253 time=43.475 ms
64 bytes from 54.172.60.0: icmp_seq=3 ttl=253 time=45.308 ms

Make sure to double check the SIP domain, username and password. You should also reset the application or try a different softphone application such as X-Lite.

For each employee, they will need to install the client and configure with their unique username/passwords (e.g. employee 1 is 18068535535, employee 2 is 18068533333, …).

We are ready to try and see if it all works. Try calling your Twilio phone number. You should hear your SIP phone ring. Answer, and verify you have two way audio.

Test that your call in Zoiper works.

In case you do not hear audio on both directions, follow the troubleshooting steps:

Check if there is a firewall or NAT (Network Address Translation) device - see if it is configured to permit packets to and from your SIP client:

Signaling IP Ports: 5060 (UDP/TCP), 5061 (TLS)
Media IP Port Range: 10,000 to 20,000 (UDP)

Check if your client is using a codec supported by Twilio - G. 711 μ-law (PCMU) and A-law (PCMA)
Try a different softphone

Try calling from your SoftPhone. You should hear the other end ring. Answer, and verify you have two way audio.

In case the call does not complete, follow the troubleshooting steps:

Go to the debugger - check for the error message.
If it is a “13214 - Dial: Invalid callerid value” - make sure you have configured the caller id properly on your softphone client. This is a good guide.

Finally, configure your PBX solution to forward the calls to your Twilio phone numbers. Test if a call to the extension defined gets forwarded to the correct Twilio number, and if the right SIP softphone rings, and when answered, audio is good.

We are now all set to work from home!

Use Twilio Programmable Voice to enable working from home

In this blog, you have learned how to use Twilio Programmable Voice to create a simple solution to allow employees to work from home.

If your organization would like more guidance on how to build solutions or would like to partner together on your work addressing the outbreak, we’re here to help. Reach out to coronavirus@twilio.com.

Possible improvements

If you have a large number of extensions you should consider using Twilio functions instead of TwiML bins.
Use X-Lite as a softphone instead of Zoiper.
Use an IP Phone instead of Softphones

For example, an alternative is to use Obihai’s phones:

https://www.amazon.com/OBi202-2-Port-Adapter-Support-Service/dp/B007D930YO/

https://www.amazon.com/Obihai-OBi1022-Phone-Power-Supply/dp/B00TEJOYYQ/

Follow this guide to configure the Obihai with Twilio:

https://twilio-cms-prod.s3.amazonaws.com/documents/Give-Your-OBIHAI-Phone-Telephone-Connectivity.pdf

Guides for other IP Phones are here:

https://www.twilio.com/docs/voice/api/sip-registration#configure-your-sip-endpoint

Additional resources

The following reference resources will provide you with in-depth information on some of the topics mentioned in this post:

Programmable Voice – The Twilio documentation includes quickstarts for popular programming languages, including C#, and reference information on advanced features.
TwiML™ for Programmable Voice – The documentation for TwiML, the Twilio Markup Language, will tell you all about the special XML tags you can use to build programmable voice applications.
Registering a SIP Phone Directly to Twilio (and so much more...)

Authors