Introduction

Following on from the work detailed in my previous post here are some details on a couple more tweaks that, whilst a little more advanced, add some important functionality.

Callbacks

 The Problem

Although I provided a refresh button on the administration page, I wanted to have the page refresh the ongoing call data itself. In theory this could be done by simply having the page run the refresh routine periodically, but doing so is somewhat frowned upon by companies (and I suspect Twilio is one of them) as it means you are contacting their server every five seconds to be told that there isn't a conference currently running.

 The Solution

Twilio, like many companies with an externally available API, offer a "callback" functionality. This means that, rather than us asking the server every 5 seconds if there is a change, they will tell us when a change happens. In the case of conference calls, Twilio can tell us whenever the conference starts or stops, or when a participant enters, leaves, mutes or is unmuted. We can then store this this information locally and our page can request it whenever we want without affecting Twilio

 The Method

Local changes

First you will need the updated index.php file from [here](), the new ajax.php file from [here]() and then a new file called callback.php from [here](). Put these into the same place that the rest of your admin server lives, overriding the originals. (Note that the new index.php file also contains code for the second change in this update, for service replay)

Twilio changes

Now you need to tell Twilio about your callbacks. From the Twilio Console, edit your TwiML Bin (see previous post for details on this) so that the conference line instead reads something like this:

<Conference muted="true" statusCallback="https://mychurch.org/conference-dialler/callback.php" statusCallbackEvent="start end join leave mute">Sunday-Service</Conference>

This will tell Twilio where your callback is, and for what type of events you want notification. Save this.

The Result

You should now find that when you're on the administration page, the conference details will periodically (roughly every 5 seconds) update with the current list of callers, without needing to press the refresh button. The refresh button is still linked to code that will update directly from the Twilio servers, but we are now also storing current details in our local database.

A note on Security

Note that if you have implemented any security on your page, for instance putting it behind an .htpasswd authentication, then you will either need to provide a way for Twilio to give that authentication, or you will need to make the callback.php file available without authentication.

Service Replay

 The Problem

With the existing sytem, anyone can call into the conference line at any time. Twilio will start a conference, but they will hear nothing and not be able to say anything. What would be nice is for the system to know that a service is not currently running and instead provide the caller with the option to listen to a playback of the most recent service.

The Solution

If we are administering the service from our panel, we can easily indicate whether or not a service is currently running. Twilio can ask us this using a 'webhook' and route the call accordingly.

 The Method

 Local Changes

You will need the new webhook.php file from [here]() and an updated quickstart.js from [here](). The webhook goes in your main folder, and the quickstart.js into the js folder.

You will need to edit the webhook.php file with some additional information:

1. On line 15, you need to enter the URL of your service podcast. This should be an RSS feed, not an iTunes itms link. If you're not currently podcasting your service audio, then there are plenty of services to allow you to do so. NOTE that Twilio recommends that streamed audio over calls should be less than 40 minutes long - we reduced our recordings to the Scripture reading and the sermon, rather than a full service replay.
2. On line 18, you need to enter the URL of recording voice message - something like "There isn't a live service at the moment, but here is a recording from". Note that:
   • The system will use an automated voice to play the date of the most recent recording from your RSS, so you need to end your voice message appropriately.
   • You can use a Twilio asset to store the recording if you like - details on how to do this are in the previous post.
3. On line 23, you need to enter the URL of your service introduction message - this will the same URL that is in your TwiML bin.
4. On line 25, you need to enter the friendlyName of your conference, and the URL of your status callback - again this is the same information as your TwiML bin.
5. Save the file.

Twilio Changes

We now need to point Twilio to our webhook.

1. Select "Phone Numbers" from the Twilio menu, and then select your phone number. Scroll down to the "Voice & Fax" section, and in the section "A Call Comes In" change this from TwiML Bin to Webhook, and then put the URL of your webhook ( https://mychurch.org/conference-dialler/webhook.php ) into the box. Leave the end dropdown set to HTTP POST.
2. In the following section called "Primary Handler Fails" select "TwiML Bin" in the dropdown and then your Sunday Service Conference Line from the next dropdown. This ensures that if there are any problems with your code, the system should fall back to your original state.

Important Note

If you are running your conference using the built-in dialler from the administration page, then this will automatically start and stop the service when you make the initial call and hangup that call. If you are using a different device, you will need to use the "Start Service" button prior to calling the line with that device to prevent it just routing to the service replay. The callback code will automatically end the service whenever it receives the conference-stop event from Twilio

The Result

We now have a single phone number that, on Sunday mornings, will conference callers into the live service audio, but for the rest of the week will allow them to listen to audio from a recent service.