Keeping Closer Tabs on Your Numbers with Twilio Monitor

Keeping Closer Tabs on Your Numbers with Twilio Monitor

Phone numbers are like any business inventory. If not properly managed, problems can snowball. Think about what happens when a number is mysteriously misconfigured and stops working; or you ended up with 50 new numbers in Tallahassee when you only needed 5; or someone accidentally deletes a phone number for one of your biggest customers.

If you manage 10 numbers this can be annoying. Now think about an online marketplace with hundreds of numbers for call tracking. Or a Twilio-powered multinational call center built with thousands of numbers. The Twilio Account Portal or IncomingPhoneNumbers API gives you a nice snapshot of the current state of your numbers, but it can’t give you the historic detail you need to look back and troubleshoot these types of problems with so many numbers.

There’s a better way now, and it’s called Twilio Monitor. In the next couple months, I’d like to offer you some tips on using Monitor to address phone number inventory and some of the other common questions we get from our customers.

For the uninitiated, Monitor gives you detailed visibility into the operations of your Twilio account and Twilio applications. It’s easy to visualize and examine the most relevant data and you can store data for as long as you need it. By retaining this data, you have a way to run security forensics, perform internal audits and comply with industry regulations.

So let’s talk about how to use Monitor to tame phone number inventories.

Tracking Changes

Monitor now offers a REST resource called Events, which gathers granular details of phone number’s history.

Whenever your Twilio phone number is created (provisioned), deleted (released), or updated, Twilio will write a unique event that details which phone number was impacted, how it was impacted, and who executed the change.

In addition to accessing Events from the API, you can visualize the data in the Account Portal. Here’s what it looks like.

Event writing is turned on by default, and each event is set to be saved for 30 days. The duration of the event storage is customizable and many users will bump it past 30 days to ensure the data is available for troubleshooting or to show compliance  with industry standards or internal policies.

Now let’s take a look at how we might audit a number.

Available when you need it

Once the events are written, you can access them, or “read” them whenever needed.

Let’s take the example of a phone number that is is no longer working correctly, and all calls made to this phone number result in the caller hearing those dreadful words: “An application error has occurred”.

We now know that Twilio is trying to fetch invalid TwiML from the specified URL when the phone number is called. But how did this happen? You have many scripts that update your phone numbers’ voice URLs, but which one was it?
To start troubleshooting, you can first go into the Account Portal to the Monitor tab and select ‘Events’. By using the drop down to filter the Event’s Log by Resource SID and then pasting the SID for the phone number in question, you obtain a historical record of all saved events related to that phone number. This includes an event for every time the phone number was updated, which allows you to click into each event and see where any voice URLs were changed or misconfigured.

This is the manual way to check what happened, but maybe you want to systematically log phone number changes so you have a record of them in your database, can immediately notify the right people, and so on. To do this, write a program that polls the API and stores any Monitor Events for phone number updates.
With Monitor, we can GET the event history of this phone number via the Events REST Resource. All we need to do is specify what phone number we are interested in (using its Resource SID), and ask for the date it was updated (event_date) and what changed (event_data). Furthermore, if you enjoy pointing fingers (and who doesn’t?), you can also query for the user that made the change (actor_sid). In Python (-v 2.7.9), the request would look like this:

The output should give you a list of each event and their requested properties for the specified phone number:

Full documentation on the Event REST Resource here

With the ability to dynamically fetch event information, you can correlate data from other internal systems for faster, more holistic troubleshooting.

What Else?

This is only one of the ways you can take advantage of writing and reading events with Monitor. Stay tuned for more best practices that use various types of events to troubleshoot applications, increase your security measures, and adhere to industry specific standards. For the time being, we recommend going into your account and checking out the list of events Twilio can write, and then selecting how long you would like Twilio to save your events.