Published by Michael Bigg on Wed, 29 Apr 2020 20:55

Warning: This post is quite technical!

On the back of my post about using Zoom and Twilio to enable people to dial in to live services, I've been inspired to think about those who are, perhaps, getting a little forgetful and say they'd like to listen in, but then forget.

What if we could make a phone call to people in our congregations that would connect them through to our live service when they pick up? That's what this blog post explains...

Before you start

To make this work you'll need a couple of things ready:

  • A Twilio account with some paid credit and an active phone number.(By the way, if you're signing up for Twilio, please consider using my referral code, then we both get $10 of credit when you first add credit of your own).
  • A Zoom account - last time I checked this need to be a paid subscription for dial-in to work, but I can't find the thing that said that any more.
  • Optional: An MP3 recording of you greeting the people that you are calling. There's an option to generate a computer voice to say hello, but I suspect many people would hang up straight away if they hear this!
    • My recording says something like: "Hello! It's Mike from the church. Our service this morning is about to begin. If you'd like to listen in please hold the line and there'll be about 10 seconds of silence as we connect you. If not, then please just hang up and have a lovely day!"

Creating a dial-out service

To make this work you need three things: a function, a flow and a trigger. (Optionally you also need an asset if you have an MP3 recording to play).

  • The function is what tells Twilio how to send the call on to Zoom.
  • The flow tells Twilio how to handle the call in general.
  • The trigger is what initiates the outbound call in the first place.

Let's create these one by one.

Step 1: Creating your Function

The first thing to do is to go to the Twilio functions page. It should look like this. Click on the red + symbol:

Select "+ Blank" in the option box that comes up and click "Create" in the bottom right.

Give your new Function a "name" (something like ZoomForward) and a path (something like "/zoomForward"). Now copy and paste this text into the code section:

/**  *  Call Forward Template  *   
*  This Function will forward a call to another phone number. If the call isn't answered or the line is busy,   
*  the call is optionally forwarded to a specified URL. You can optionally restrict which calling phones   
*  will be forwarded.  */  
exports.handler = function(context, event, callback) { 
// set-up the variables that this Function will use to forward a phone call using TwiML      
// REQUIRED - you must set this (will default to a standard Zoom number
let phoneNumber = event.PhoneNumber || "+442030512874";          
// generate the TwiML to tell Twilio how to forward this call   
let twiml = new Twilio.twiml.VoiceResponse();
// These digits will enable your listener to get straight into zoom by dialling the meeting ID and password automatically
let digitsToSend = 'wwww' + event.zoom_meeting_id + '#wwww#wwww' + event.zoom_password + '#ww';       
const dial = twiml.dial();         
dial.number({             
sendDigits: digitsToSend         
}, phoneNumber);      
// return the TwiML   
callback(null, twiml); 
};

It should look something like this:

Now you can click "Save" and step one is complete!

Step 2: Create a Flow

This bit tells Twilio how to make an outbound phone call.

  1. First thing is to open Twilio Studio and click the red + to make a new "Flow".
  2. Give your Flow a name like "Dial out service", click Next.
  3. Select "Start from Scratch" and click Next.

Your new flow should look something like this:

 

Step 2.1: Make an outgoing call

We want to make an outgoing call to someone, so drag-and-drop the "Make Outgoing Call" option from the "Widget Library" on the right onto the blank space in the middle of the page.

You can give your new "widget" a name, if you like (other than "call_user_1"). Then work your way down the new "Make Outgoing Call" widget options that should have appeared on the right hand side of the screen.

  • Set "Detect Answering Machine" to "On".
    • This is optional, but if you don't do it and someone sends your call to voicemail then you may well end up leaving a lengthy voice recording of a service. You won't make any friends this way!
  • Leave "Machine Detection" as "Detect Machine Start" (so that we know when an answering machine picks up.
  • Put "Machine Detection timeout" down to about 5 seconds (this is the length of time after which Twilio will give up detecting an answering machine).
  • Put "Machine Detection silence timeout" down to 2000 ms (if someone picks up and says nothing it'll give up after 2000ms [2 seconds]).
  • Click "Save" at the bottom.

There'll be a red circle exclamation mark on your Outgoing Call widget because it's not connected. You need to drag the "red blob" coming out of the Trigger called "REST API" at the top down to the black circle in the top left of your new widget. It should look something like this.

Step 2.2: Check who answered...

Now we need to check who actually picked up the phone. Human or answering machine?

  • Click on a blank space somewhere to get the widgets panel back.
  • Find the "Split based on..." widget and drag and drop it into a space.
  • Drag the grey blob from the "Answered" output of the "Call Out" widget onto the grey circle of the new Split widget.
  • When you click on this widget, find "AnsweredBy" in the "Variable to Test" box.
  • Click the red "New" on your split widget, then select the "Condition Matches" option.
  • Where it says "Enter value" type "human".

Your flow should look like this:

 

Step 2.3: Say something!

By this point in the flow we've made a call to someone and checked whether an answering machine has picked up. If a human has answered the phone, we want to say something to them! 

  • Click on a blank space in the flow screen to get your list of available widgets back.
  • Scroll down the list to the "Say/Play" widget and drag and drop it into a space underneath the last one.
  • If you have an MP3 audio file to welcome people, change "Say or Play a message" to "Play a Message" and then put the link to your welcome message in the "URL of audio file" box.
    • If you don't have an MP3 then you can type in a message to welcome people. Twilio will say your message in a computer-generated voice.
  • Click "Save"
  • We want this to happen when a human answers the phone, so drag the black blob coming out of "if value equal_to human" on the "Split widget" to the black circle at the top left of your say/play widget.
    • You can leave the other blobs from the outgoing call hanging. If any of these happen Twilio will hang up.

You should now have something like this:


Step 2.4: Route through to Zoom

Now we've said hello to whoever has picked up we need to send them into our Zoom service.

  • Click in a blank space to get the list of widgets back.
  • Scroll down to the "Run Function" option (listed under "Tools & Execute Code")
  • Drag and drop this function into some space.
  • In the "Function URL" box select the Function that you created in Step 1.
  • Click + next to "Function Parameters"
    • In the "Key" box write zoom_meeting_id
    • In the "Value" box write the Meeting ID of your Zoom meeting that's hosting the service. (You'll save a lot of effort if this is a recurring Zoom meeting so it's the same Meeting ID each time!)
    • Click the grey, underlined "Save" link (not the red box!)
  • Click + next to "Function Parameters" again
    • In the "Key" box write zoom_password
    • In the "Value" box enter the password for your Zoom meeting.
    • If you don't have a password just enter 1.
    • Click the save link again.
  • Drag the grey blob from the "Audio complete" bit of the Say/Play widget onto the grey circle in the top left of your Function widget.
  • This tells Twilio to run the Function we created earlier, and will send Zoom the meeting ID and password we've included.

Your page should look something like this:

Now click "Publish" at the top. It'll ask you to confirm. Click "Publish" again.

Hurrah! We now have a flow that will call someone and send them through to our meeting!

Step 3: Triggering our Twilio Flow

In order to actually make the phone call we need to tell Twilio to actually make it happen. This is as simple as visiting the right website, but we need to send the right data.

  • Open up a text editor (like Notepad, not Microsoft word) on your computer.
  • Copy and paste this code into it:
<h1>Dial-out generator</h1>     
<p>Fill in the form below to invite someone to your live meeting on Zoom</p>
<p><b>Make sure the Zoom meeting is running before you run this!</b>
     <script type="text/javascript">     
        function get_action(form) {
             form.action = "https://" + form.sid.value + ":" + form.auth_token.value + "@studio.twilio.com/v1/Flows/" + form.flow_sid.value + "/Executions";
     } 
</script>
<form onsubmit="get_action(this);" method="post">
      <p>Twilio Account SID: <input type="text" name="sid" value="AC"> - your Twilio account SID. (Find it at <a href="https://www.twilio.com/console">https://www.twilio.com/console</a></p>
      <p>Twilio Account auth token: <input type="text" name="auth_token" value=""> - your Twilio account auth token. (Find it at <a href="https://www.twilio.com/console">https://www.twilio.com/console</a></p>
      <p>Function SID: <input type="text" name="flow_sid" value="FW"> - your Twilio flow SID (find it in the Twilio Studio)</p>
      <p>From number: <input type="text" name="From" value="+44"> - your Twilio phone number</p>
      <p>To number: <input type="text" name="To" value="+44"> - the number to dial</p>
      <p><input type="submit" value="Go"></p>
</form>

Save your document somewhere with a filename like dialout.html

To make this code work you'll need 5 extra pieces of information.

  • Your Twilio account SID. You'll find it on the Twilio Console
  • Your Twilio auth token. You'll also find it on the Twilio Console
    • WARNING: Your account SID and auth token are, in effect, your username and password for accessing Twilio. Anyone who has them can use your account to make calls. Save the file you are creating somewhere safe!
  • Your Flow SID - This is on the Studio Dashboard and is the long piece of text that begins "FW" next to the Flow you've created.
  • Your Twilio phone number - this is the number you have bought through Twilio. Make sure you format it as +44 <dialing code without a leading zero> <number>
  • The number you want to call - format it properly too (+44 etc).

If you want to save time, then you can save the first four bits of information in the file you just saved. (eg. put your Twilio Account SID in the line that starts: 

<p>Twilio Account SID: <input type="text" name="sid" value="AC">

Instead of value="AC" put your entire Account SID inside the quotes. Similar with your auth token, flow SID and Twilio number.

Now open the file you've created in a browser like Google Chrome. It should open a web page that looks a bit like this. It might include more information if you entered extra details as per the note above.

Finally, enter all the relevant information into the boxes and hit "Go!" (Make sure your Zoom meeting is actually running first!)

This will use all the information from the form to trigger the flow we created in step 2. Obviously, I recommend that you use your own phone number to test this out first! Any calls using this method will use your Twilio account and phone number, so don't go making prank calls! If you are going to use this, you really ought to let the person you are calling know that it will happen first...

Costs

It costs $0.015 per minute to dial into Zoom. It also costs the same to call another landline. Therefore if you're using this service to ring someone's landline it will cost you roughly 3p/min (and won't cost anything for the person receiving the call).

If you are calling someone's mobile telephone it costs $0.029/min, so a total cost of ~4p/min.

There is also a cost of < 1p per call to use Answer Machine Detection (I think it's $0.0075 each time).

If you ring someone on a landline and they listen in for a whole hour-long service it'll cost you ~£1.50, which I think is a fair price to help someone without internet access join a service.

What happened to my call?

Once the call is made it's out of our hands as to what happens. However, if you open your "Flow" and click "Logs" on the left you'll get a record of all the different times the Flow was executed, and you can see roughly what happened...


Please get in touch if you have any questions, or anything here doesn't quite work for you. I'll do what I can to help! 

If you've actually done these steps and made it work for you I'd be glad to know that it actually works for someone else!

Email: mike@eastleightonstone.com

Final Thoughts

I'd like to write something about the practicalities of listening to a service on the telephone. Please let me know if you have any hints / tips / advice on making people listening to a service on the phone feel connected. If you have called the Church of England "Daily Hope" hotline you might appreciate how easy it is for phone connections to feel very impersonal. If you've done anything to make the experience better for people on the phone please let me know!

Also look out for https://faith.online/, who are launching a product tomorrow (I think) that is intended to make all of this kind of thing much simpler!

 


Categories Curate's Blog

Comments

John E
Tuesday, 5 May 2020 18:08
Thanks for this, I think it will be very welcome to our older members. I did get this working, but with some hiccups. Firstly I think the greeting mp3 needs to be stored as an asset within Twilio, which I don't think is covered clearly above. Also I have to adjust the digitsToSend as follows:
let digitsToSend = 'wwwwwwwwwww' + event.zoom_meeting_id + '#wwwwwwwww#wwwwwwwwww' + event.zoom_password + '#ww';
So as not to get zoom asking me for a password. I think the downside of this is that there is a longer silence and I have not tried tweaking these "w"s down to see if I can get it quicker, but still reliable. Also I found the answering machine detection too unreliable, so I went with getting the user to press a button to listen or just hangup. Also I think it is necessary for the zoom meeting to have a numeric password, although in the circumstances I may not end using a zoom password at all.

Add new comment