Replacing Hold Music With New York Times Headlines


So I was straight chillin’ on the Internet, fixing to moderate another troll post on my favorite Justin Bieber fan forum, when my buddy Amit posts on Twitter:


I said to myself, “Hey self, Amit is right. That would be cool.”

Out With The Hold, In With The New York Times

Twilio’s Conference noun sports functionality that lets you customize the hold experience.  The <Conference> waitUrl value accepts any valid TwiML document, which means instead of playing some lame elevator muzak, I can use most of the Twilio vocabulary, including our newly improved <Say> verb.   Further, I live in a town with a mighty fine newspaper that can be programmatically poked to spit out JSON of today’s headlines.  With these ingredients firmly in hand, we have all we need to turn Amit’s tweet into reality in little less than an hour with full unit testing.

In this post we’ll look into how to replace your humdrum hold music with today’s headlines from The New York Times, read to you by the soothing voice of Twilio’s new Alice text-to-speech voice.

Building The Conference Room

We’ll be using Python’s micro web framework Flask for this project.  If you want to cut to the chase, the completed project with instructions on installation and configuration are available here.  You can also give it a try before you code by calling (646) 430-9298.

Let’s hop to it!  First, we need to create a Twilio Conference room with a Flask app.  Simple enough.

If we set the Voice Request URL to the /conference endpoint we created above – bliggity-blam – that caller is placed into a conference.  Now we need to take that hold experience and customize it.  To do this, we use the waitUrl attribute of the Conference noun and connect it to a new endpoint called /wait.

Nice!  Our callers hear a custom message when they try to call into the Conference.  Now we just need to get some more interesting information for them to hear – like today’s headlines from the New York Times.

Connecting to the New York Times API

Next we’ll slow down a bit and go step-by-step through how we get the latest headlines from the New York Times API and transform that data into something our callers can hear while they wait to be placed in conference.

First, we need to sign up for an account on  Next, we need to go to the New York Times Developer Network site to get an API Key.


Step two is to click the Get Keys button to register our application.


Boom!  Now we can enter the information for our application which is step three.  Fill out the name of the application, your web site and how you heard about the New York Times API.  After this information is filled out we will scroll down.


As we are scrolling down, we see a multitude of rad APIs from the folks at NYT.  The one we are looking for in step four is the one that will give us today’s most important stories – the Most Popular API.  Select the checkbox for “Issue a new key for Most Popular API” and continue scrolling down to the bottom.


Step five, we agree to the New York Times Terms of Service and register our app.


And holy biscuits!  We now have our API key.  Copy this value – we will use it as we continue coding our informative new conference wait room.


Connecting Your Conference Room To The News

Excellent – now we’re ready to fill our conference wait room with all the news that is fit to print.  To do this, we need to ask the New York Times API for the Most Popular articles for the day.  For that we will use a favorite HTTP client of mine, Kenneth Reitz’s elegant Requests module.

Once we successfully retrieve with a Requests call, we’ll iterate through the results and pull out the NYT’s handy data field called abstract.  This field which will give us a string of that news story to read to our callers using the new Alice voice in a Say verb.  Finally we’ll add a pause after each Say so our callers will know they are hearing another headline.

What’s Next

News headlines are just the tip of the iceberg of what you can do with waitUrls.  The same idea could be applied to callers entering a Twilio Queue.  You could also reduce the stories down to sections of The New York Times that appeal more directly to your callers like Business or Technology.  Or you can surprise and delight your users with something completely different.

To get a more fleshed out version of this project, check out this repo on Github with a full test suite and better error handling.  Or you can try it out for yourself by calling (646) 430-9298.

The waitUrl attribute is one of my favorite features of the Twilio API and I can’t wait to see what creative hold experiences you create.  Be sure to share them with me on Twitter @dN0t or by email at

  • TJ Thompson

    cool idea.

  • John Doe

    You burry the key but right under it’S still there hhahahahah