Bring Live Transcription to Your Existing PABX

February 20, 2020
Written by
Stuart Logan
Contributor
Opinions expressed by Twilio contributors are their own

live-transcribe-pabx.png

I often find myself in conversations with customers who are unsure about where to start with Twilio and their PABX. They have a great idea to improve customer experience, but they usually have an existing PABX that doesn't allow them to innovate at the speed they need to differentiate.

Most start to plan how they can retire their existing estate. Quickly, they realize that it is going to be an uphill battle. Many then resign themselves to the "that's just how it is" mentality, log a feature request with their existing vendor, and then hope that enough other customers want the same feature that the vendor builds it.

But what if there was another way? With Twilio Programmable Voice, you can keep your existing PABX and introduce cutting edge features and technology into a roadmap that you own.

The Problem: Lack of Real-Time Transcription

I faced this situation with a customer recently. Their existing PABX still satisfied the majority of their business requirements, and staff was happy with the handsets they had and their general workflow.

What was missing? The ability to transcribe calls in real-time.

If people didn't have to take notes manually they'd be free to focus on the conversation they were having, their notes would be more accurate, and they'd be entered into the system of record in a timely fashion. This just wasn't something on the vendor's radar, and the system didn't offer an API to integrate external services.

The Solution: Integrating Twilio

A picture is worth a thousand words – or in this case, potentially billions of transcribed words – so let's start with a diagram.

PABX Media Stream WebSequence Diagram

The Setup: Configuring Twilio

The first questions that cross people's minds when considering incorporating Twilio are: What do I do with my phone numbers? Do I need to port them to Twilio?

You certainly could, but you're looking to complete this setup today – you can instead verify your existing numbers to use as caller-ID for your outbound calls. Follow the instructions here to set it up.

Verified Caller ID Console Sample

Next, we need to configure a SIP Domain. This is the core of how we get voice traffic from your PABX to Twilio to unlock the power of Programmable Voice. The first thing to do is to create a SIP URI and ensure your DNS and firewall will forward SIP traffic through to your PABX.

The Voice Configuration Request URL is where you define the endpoint for your web application. This is where Twilio will send webhook requests, and your application will apply the necessary business logic and return a set of instructions (called TwiML) to let us know what to do next with the call. We'll see what that looks like soon. The Fallback URL serves as a backup if your web server is down. (A good idea is to have a static TwiML bin to make sure the call can progress in some form rather than return an error.) The Status Callback URL can be used to provide real-time updates to the progress of the call.

The last thing we'll need to do is set up some authentication. This applies to the INVITE for inbound calls to Twilio to ensure we're getting traffic from the right place. You can choose to set up an IP Access Control List, a more secure Credential List with usernames and passwords, or both. Do not turn on SIP registration. This is used for configuring SIP endpoints directly to Twilio and doesn't apply to this example.

SIP Domain console example

For more information on configuring your SIP Domain, refer to the information here.

Configuring the PABX

And that's it for the Twilio side. Now, let's look at what's required on the PABX side.

I'm using FreePBX for my examples, but the theory applies to any PABX. I'm going to assume you already have a working and configured PABX with at least one extension. 

Here's mine, extension 201, configured with an X-Lite softphone:

FreePBX Extension 201

A SIP trunk is how we're going to get our calls to Twilio. Configure a trunk on your PABX that points to the Twilio SIP Domain you created and using the access credentials you defined.

SIP Trunk FreePBX

 

Configure your dial plan to send outbound calls over the trunk you created. In this example, I'm sending all calls to it.

Outbound Route FreePBX

 

Dial Plan FreePBX

 

So our PABX can now talk to Twilio! How do we use that to augment the existing PABX capabilities? Well, now, when a call is made, the SIP Domain will send a webhook to the Request URL you defined in the configuration.

It will look something like this:

Form Parameters

AccountSid

ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ApiVersion

2010-04-01

Called

sip:+447860141XXX@stuartlogan-freepbx.sip.twilio.com

Caller

sip:201@192.168.86.21

CallSid

CA0a01c5359707cec13352a256ec5c0952

CallStatus

ringing

Direction

inbound

From

sip:201@192.168.86.21

SipCallId

b31c95e6-1d25-4d2e-a263-a0a3d9bf7f3e

SipDomain

stuartlogan-freepbx.sip.twilio.com

SipDomainSid

SDc857b790aecf66f47902082301c35821

SipSourceIp

86.141.137.161

To

sip:+447860141XXX@stuartlogan-freepbx.sip.twilio.com

To breakdown what happened:

  1. Extension 201 picked up the phone and dialled +4478060141XXX
  2. The PABX (192.168.86.21) used the configured outbound rule to send this call to the Twilio Domain.

Behind my Request URL is a Python Flask application. The /twiml route that is configured is below:

@app.route('/twiml', methods=['POST'])
def return_twiml():
   to_param = request.form['To']
   print(to_param)
   regex = r"\+[0-9]*"
   matches = re.search(regex, to_param)
   num_to_dial = matches.group()
 
   print("POST TwiML")
   return render_template('streams.xml', num_to_dial=num_to_dial)

A simple regular expression captures the E.164 portion of the phone number, that is, it removes the @stuartlogan-freepbx.sip.twilio.com (domain) part of the URI

At that point, you have a number, and you need to get Twilio to dial it. At that point, the number is passed into the TwiML response and returned.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
 <Start>
   <Stream url="wss://edef7de2.ngrok.io" track="outbound_track"></Stream>
 </Start>
 <Dial callerId="+44747XXXXXXX">{{num_to_dial}}</Dial>
</Response>

The TwiML instructs Twilio to start a media stream to my application and then Dial the far end number, which, when answered, will connect this party to extension 201. The media stream is then sent to a transcription engine of choice, which then returns the audio as text.

(How media streams work is beyond the scope of this blog, but you can read more about them here.)

Transcription alongside x-lite call

 

Augmenting Your Existing PABX with Twilio

This is just one way to augment the capabilities of your PABX. The conversation is no longer about "rip and replace" or paying more for licensed features. Now it's how you can use your existing infrastructure to do the bits that it does well while incrementally adding functionality.

If you want some other ideas of where else you could start with Twilio SIP Domains, how about adding WebRTC capabilities or taking back control of your IVR with the added help of Twilio Studio?

I can't wait to see what you augment!

Stuart Logan is part of the Twilio Solutions Engineering team based in the UK. He comes from a traditional communications background and is amazed every day by what developers can do with Twilio. If you have any questions, please feel free to contact him on Twitter, LinkedIn, or Github.