Home > LiveOps EXTRAS! > Application Notes > App Note 017 - Integration with Whitepages Pro

App Note 017 - Integration with Whitepages Pro

Abstract

The LiveOps Call Flow Authoring tool has the ability to exchange data with external sources. These data exchange features can be used, for example, to extract a caller’s Caller ID (or collect DTMF digits into an Account_Code variable) and query a customer’s database for a matching contact and return values such as REGION, STATUS, PRIORITY, etc.

This Application Note will describe the use of these capabilities to query an external service called Whitepages Pro to gather and use data for call routing and for display to agents. Screen pops will also be discussed.

Introduction to Whitepages Pro

Whitepages (www.whitepages.com) is the leading source for personal and business contact information including names, addresses and phone numbers. With over 50 million unique monthly users, Whitepages provides access to more than 300 million identities accessible via its web and mobile tools. Whitepages also operates Whitepages Pro, an API and web-based service, helping businesses verify the identities of their customers.

As part of their Reverse Phone lookup service, Whitepages Pro can provide detailed phone information including names, demographic data, addresses and more; even when the numbers are unpublished. This allows a customer to identify their callers in real time even when the caller’s Caller ID information is previously unknown to the company or is from an unlisted number.

For example: say someone dials into your company’s premier support queue’s direct number. You may want to take the caller’s Caller ID number (also known as their ANI, or Automatic Number Identification number) and look that caller up in your company’s CRM database using the Data Exchange features of the LiveOps Platform Call Flow Authoring tools.

If you find a match, the LiveOps system can retrieve data such as “CONTRACT_STATUS” to see if their support contract is still valid. If valid, route the call into the queue for the next premier support representative. If not valid, re-route the call to a “renewals team” instead of your “premier support team.”

But what if the caller’s ANI is not found in your CRM? Should you still route that call through to a premier support representative? Or might you consider redirecting the call to a front desk receptionist so they can “triage” the call? Would it be helpful to present that receptionist with some information about the caller first? Could that improve the efficiency or accuracy of the receptionist’s work?

What if the caller is an annoying sales person who is calling to sell you something you don’t need or even a fraudster? If the system could “trap” those “spam” and/or "scam" calls and send them to voice mail instead, would that save time and improve efficiency?

Or what if the caller is dialing from a non-fixed VoIP (e.g. Skype, Google Voice), toll-free, international, or pre-paid mobile number? Does that affect how you would prioritize or route the call?

These are the kind of data and insights that can be provided by integrating Whitepages Pro and LiveOps.

Overview of Solution

This Application Note will present three scenarios to integrate information provided by Whitepages Pro into the LiveOps platform:

Performing a screen pop using the caller’s ANI to display information about the calling number to the answering Agent
Performing a database lookup of the caller’s ANI to present caller information to the Agent within the LiveOps Phone Panel
Using Whitepages.com data to re-route potential “spam” callers

Scenario 1: Performing a Screen Pop using Whitepages Pro

With a paid Whitepages Pro account you have the ability to do manual searches of names, numbers and addresses via their website: https://pro.whitepages.com.

Performing a “Find by Phone Number” search (also called a “Reverse Phone Number Lookup”) will produce a response similar to the following:

Note: Actual names, numbers, addresses and other personally identifiable information (PII) has been masked throughout this Application Note.

We can automate this phone number search and its corresponding display of results by using a Whitepages Uniform Resource Locator, or URL, in the “Screen Pop” field within a LiveOps Call Flow.

The URL to generate the display above uses the following syntax: https://pro.lookup.whitepages.com/phones?number=206xxxxxxx

We can use this URL syntax in the LiveOps “Screen Pop” field. The LiveOps system will append a complete set of call attributes along with the URL generating the desired screen pop.

First, we will need to capture the caller’s Caller ID (or ANI) information into a Call Flow attribute. Then we will enter the necessary URL information in the Call Flow to generate the Screen Pop.

Step 1: Extract the caller’s Caller ID (ANI)

Call Flow objects and expressions can be used to extract information about a call in the LiveOps system. The expression we want to use is “call.ani”.

Start by logging into the LiveOps Administrative Web Portal
Navigate to “Routing > Call Flows”
Create a new call flow called “Whitepages Pro Lookup”
Click on the “Call Attributes” tab and create a new attribute called “number”

Set the “Data type” to “String”
Set the “Initial value” to the expression “call.ani”
Ensure “Use to present a screen pop” is checked
Save the new attribute

Step 2: Configure the On Call Screen Pop

Switch to the “On Call” tab and enter the following in the “Screen Pop” field:https://pro.lookup.whitepages.com/phones.

Note: In order for a call flow to function you must configure all the standard call routing components such as Incoming Numbers, Campaigns, etc. This AppNote only covers the configuration steps related directly to the Whitepages Pro services.

Now, log in as an agent, launch the Phone Panel (or the LiveOps Engage client), make yourself available and take an inbound call.

When the call is presented to you, you should see a new web browser tab open and display the search criteria within the Whitepages Pro service for the caller’s Caller ID.

You should see a web page displayed similar to the one below:

Note: The web browser used to invoke the screen pop will be the same web browser used by Phone Panel (or Engage). You must have an active login into Whitepages Pro prior to receiving the call. The Whitepages login must use the same web browser as your LiveOps login in order for the screen pop to be invoked properly. Otherwise you will be prompted to enter your login credentials.

Each successive call will display the search results in a new tab. If you desire to alter the windowing behavior (for example, you prefer that all screen pops reuse the same tab) review the window control options discussed in LiveOps Application Note #10: “Agent Screen Pop Details”.

Scenario 2: Performing a Whitepages Pro Lookup of the Caller’s ANI

In addition to simple screen pops and web services as described above, Whitepages Pro offers a broad API supporting direct database queries. LiveOps can take advantage of these APIs by using the “Representational State Transfer” (or ReST) to send a “RESTful” query to Whitepages Pro, extracting relevant information and displaying that information to an Agent or using it for reporting purposes.

In this scenario we will extract the caller’s Caller ID (ANI) into a LiveOps variable, use the Data Exchange capabilities of the LiveOps platform to perform a reverse phone number search of the Whitepages Pro service and parse through the results looking for the first occurrence of several useful variables for display to an Agent.

Understanding Whitepages Pro APIs

At this point it will be useful to provide a deeper understanding of the type of results that Whitepages Pro can return when using its APIs to conduct a phone number query.

First, you must be issued a valid API Key from Whitepages Pro. This key will be used to authenticate the RESTful queries as coming from a user or an organization with a valid account. The API Key is a lengthy hexadecimal number similar to the following: 9f6744fe22432323aabb1d4exxxxxxxx.

Contact your Whitepages Pro representative to obtain an API Key (or sign up for free trial account here:

http://pro.whitepages.com/developer.

Second, the REST GET query into the Whitepages Pro API must use the following syntax:

http://proapi.whitepages.com/2.1/phone.json?phone_number=206xxxxxxx&api_key=KEYVAL

Third, based on the query, Whitepages Pro will generate a response in a JSON format.

A simple JSON response, truncated for brevity, might look like this:

Phone.36816fef-a2df-4b08-cfe3-bcxxxxxxxxxx.Durable:
{
 id: {...},
 line_type: "Landline",
 belongs_to: [...],
 associated_locations: [...],
 phone_number: "206xxxxxxx",
 country_calling_code: "1",
 extension: null,
 carrier: "Century Link",
 do_not_call: null,
 reputation: {...},
 best_location: {...}
}

Note: See Appendix A “RAW JSON Results from Whitepages Pro” for a complete listing of a detailed JSON response from Whitepages Pro.

For long JSON responses it can be helpful to use a JSON Formatter such as the ones found here:

http://www.freeformatter.com/json-formatter.html

http://chris.photobooks.com/json/default.htm

http://jsonformatter.curiousconcept.com

The condensed results of a lengthy JSON response could look similar to the following:

Step 1: Create a New Data Source

Log into the LiveOps Administrative Web Portal and select “Configure > Call Assets > Data Sources”
Create a new Data Source Configuration
Enter a Name, Description and choose “REST” “GET” as the Data Source Type and Action
Be sure to select “Enabled” and then click SAVE THE DATA SOURCE

For Credentials select: None
For Output Type select: JSON
For Base URL enter: https://proapi.whitepages.com:443
For Path String (when using Whitepages Pro API 2.0) enter: /2.0/phone.json
For Path String (when using Whitepages Pro API 2.1) enter: /2.1/phone.json
For Query String enter: phone_number=[CALLER_ID]&api_key=[API_KEY]

Step 2: Create Input Variables

We will create two Data Exchange variables that will be used in the REST GET query to send data to the Whitepages Pro service.

Click the “+” (Plus Sign) in the bottom left corner to create two new Input variables: CALLER_ID and API_KEY
Set Transformation Type to: “Insert As is” and check “Required parameter” for both

Step 3: Create Output Variables

We will create five Output variables that will be used to extract the information from the JSON response. In our example we have looked through the full JSON response and decided to search for and extract the first occurrence of the following five values:

best_name
address
line_type
do_not_call
spam_score (or reputation_level)

We chose these values because they return, for most phone numbers, a useful and valid representation of the data available from Whitepages Pro. For details on the complete data set, refer to the Whitepages Pro Reverse Phone documentation here: http://pro.whitepages.com/features/reverse-phone.

Click the “Output” tab
Click the “+” (Plus Sign) in the bottom left corner to create the first Output variable
Enter a Name of: BEST_NAME
Example of a RegEx Query (for API v 2.0):
- Enter a Locator Type of: Regular Expression (RegEx)
- Enter the following for the Regular Expression: \x22best_name\x22:\x22(.*)\x22
Example of an Xpath Query (for API v2.1):
- Enter a Locator Type of: Xpath
- Enter the following for the Xpath Expression: root.results[0].belongs_to[0].names[0].first_name
Check Include by Default

Repeat these steps to enter all five Output Variables using the data from the table below:

Output Parameter	Regular Expression (API v2.0)	Xpath Expression (API v2.1)
BEST_NAME	\x22best_name\x22:\x22(.*)\x22
BEST_FIRST		root.results[0].belongs_to[0].names[0].first_name
BEST_LAST		root.results[0].belongs_to[0].names[0].last_name
ADDRESS	\x22address\x22:\x22(.*)\x22	root.results[0].belongs_to[0].locations[0].address
LINE_TYPE	\x22line_type\x22:\x22(.*)\x22	root.results[0].belongs_to[0].phones[0].line_type
DO_NOT_CALL	\x22do_not_call\x22:(.*),	root.results[0].belongs_to[0].phones[0].do_not_call
SPAM_SCORE	\x22spam_score\x22:(.*)
REPUTATION_LEVEL		root.results[0].belongs_to[0].phones[0].reputation.level

To test your Regular Expressions you can use a web site like the following:

http://www.zytrax.com/tech/web/regex.htm#experiment

For practice, you can use the JSON response found in Appendix A (below) and search using any of the RegEx parameters in the above table.

Here is the output of the BEST_NAME RegEx query (API v2.0)

If you want to search for content different than the five values we selected, use the web site to test and refine your RegEx queries to ensure you are able to find what you are looking for.

Note: It is important to understand that the parsing tools built into the Data Exchange interface only allow for finding and extracting the first occurrence of any variable.

In the example above, the RegEx test returns the first match as “Michelle X Xxxxxx” and an additional match as “Robert X Xxxxxxxx”. The LiveOps Data Exchange tools will only find and return the first match: “Michelle X Xxxxxx”.

If your needs require a more complicated search, or require the extraction of details beyond the first occurrence of a data element, please contact the LiveOps Professional Services team for a more customized solution.

Step 4: Test the New Data Source

Once you have entered all the URL information and created both the Input and Output variables you can test the connection. Save your data source, then click on the “Test Connection …” button.

Enter a test number, such as your own home or mobile number, and paste in your Whitepages Pro API Key. Then click “Run”.

If everything worked, you should get a response similar to the following (showing RegEx results):

You can test the URL from a web browser by using the following syntax:

https://proapi.whitepages.com/2.0/ph...bb1d4exxxxxxxx

Be sure to enter a valid phone number and your personal Whitepages Pro API key. You should get the complete JSON response similar to the one in Appendix A.

Step 5: Add Matching Call Flow Attributes

Now that the query has been constructed and tested we can use it in a Call Flow to query for an actual phone number of a live caller.

As in Scenario 1, we will only document the building of the pertinent Call Flow settings in this Application Note. You must still configure all the standard call routing components such as Incoming Numbers, Campaigns, etc.

Log into the LiveOps Administrative Web Portal
Navigate to “Routing > Call Flows”
Edit the “Whitepages Pro Lookup” Call Flow

We need to make Call Flow Attributes to match the Data Exchange Attributes we made in the previous steps. We already have the “number” attribute. Make the next one using the following steps.

Click on the “Call Attributes” tab
Click “NEW ATTRIBUTE” to create a new Call Flow Attribute
For Attribute identifier enter: WP_API_KEY
For Data type select: String
Enter a Description
For Default Value enter your Whitepages Pro API Key
Ensure “Use to present a screen pop” is checked
Save the new attribute

Make the remaining 5 attributes using data from the following table:

Attribute Name	Type	Description	Default Value
WP_API_KEY	String	Whitepages Pro API Key	<< Your API Key >>
WP_NAME, WP_FIRST, WP_LAST	String	Whitepages Pro NAME field (or FIRST and LAST fields for API 2.1)	unset
WP_LOCATION	String	Whitepages Pro LOCATION field	unset
WP_SPAM	String	Whitepages Pro SPAM/RISK level	unset
WP_LINE	String	Whitepages Pro LINE type	unset
WP_DNC	String	Whitepages Pro DO NOT CALL field	unset
WP_PREPAID	String	Whitepages Pro IS PREPAID field	unset

When finished, you should have Call Flow Attributes similar to the following:

Step 6: Modify the Call Flow to use the Data Exchange Module

Click on the “Arrival” tab to edit your Call Flow
Add a “Data Exchange” module from the “Data” Actions Palette
Select “Whitepages Pro” as the Data Source
Select the appropriate value from all the drop downs to map each Data Source Variable with its associated Call Flow Attribute

Step 7: Change the Screen Pop to Display the Data to the Agent

Finally, we need to alter the Screen Pop settings to display the newly retrieved variables instead of popping to the Whitepages Pro web site.

To do this we will use the QuickPop feature of the LiveOps Phone Panel.

Note: For more details on using QuickPop see LiveOps Application Note #10: “Agent Screen Pop Details”.

Click the “On Call” tab
Edit the “Screen Pop” field to have the following:

?quickPop=Whitepages PRO lookup - Name:${WP_NAME}, Address:${WP_LOCATION}, Line Type:${WP_LINE}, DoNotCall:${WP_DNC}, Spam Rating:${WP_SPAM}

Save the Call Flow

Now, log in as an agent, launch the Phone Panel, make yourself available and take an inbound call.

When the call is presented to you, your Phone Panel should display all the details that were extracted from the Whitepages Pro lookup.

Your Phone Panel should look similar to the one below:

Scenario 3: Re-routing Based on SPAM Score

Whitepages gathers a tremendous amount of actual call data throughout North America that it uses to generate profiles of calling number activity. They evaluate data such as inbound vs. outbound calling ratio; disconnects by the calling party vs. by the called party; and average length of call (among other factors) to generate a SPAM score to help a company ascertain whether an inbound caller is a likely prospect or customer … or is a likely sales person or robo-caller.

This SPAM score can be extracted from Whitepages Pro based on the calling number and used to divert calls that exceed a certain SPAM threshold. At the time of publishing this Application Note, a SPAM value of 0 or 1 was a strong indicator of a valid, or normal, end consumer. A SPAM value of 2-3 was suspicious; and a SPAM value of 4 or more indicated a high likelihood that the number is not being used by a standard household member but instead for “robo-calls” or other non-consumer activity.

In this example scenario we will use the SPAM value to route any call with a value of 4 or higher to a pre-recorded message and then disconnect the call. We will build upon the Data Exchange example in the previous scenario but will add an “If : Then : Else” branch.

Edit your “Whitepages Pro Lookup” Call Flow
Below the Data Exchange module, drag and insert an “If : Then : Else Branch” module from the “Flow Control” Action Palette
For the “If” condition enter: attribute.WP_SPAM >= 4
Insert a “Play Audio” module and a “Hang up on Caller” module into the “True” condition location

Record and select an appropriate audio prompt such as:

“Sorry – we do not accept calls from numbers that are seen as unauthorized or from commercial enterprises. If this is in error please call back from your home or mobile number. Thank you.”

Another valuable piece of data that could be extracted from Whitepages Pro and used to alter call routing is the “Pre Paid” flag. If a caller is dialing from a pre-paid cellular phone you may decide that they do (or do not) belong to the market demographic that is best suited for your clientele. You could choose to route or re-route callers that had the “Pre-Paid” value set for their number.

Conclusion

In summary, the Data Exchange and screen pop tools within the LiveOps platform provide a powerful set of features that can be used to enhance the agent experience and the customer’s interaction. This can improve first call resolution, speed the collection of data from new callers, intelligently route calls to the most appropriate point of first contact and help conserve the valuable manpower and resources within a customer-focused organization.

This Application Note provides an overview of using an outside service like Whitepages Pro to gather, display, route and screen pop data about a calling customer for use by the answering representative.

These principles, concepts and tools can be used in myriad ways to help improve the customer experience for your clientele and the capabilities of your agents.

Special thanks to the staff of Whitepages Pro who provided invaluable assistance in testing and creating this Application Note.

Additional Resources

Call Flow Authoring – Expressions: https://<<TENANT>.hostedcc.com/mason/admin/doc/pagehelp/callflow/chapter5.html
Call Flow Authoring – Objects: https://<<TENANT>.hostedcc.com/mason/admin/doc/pagehelp/callflow/chapter6.html
LiveOps Application Note 10: Agent Screen Pop Details
Whitepages Pro API Documentation: http://pro.whitepages.com/features/api-overview

Version Information

Date	Version	Contributor	Content
December, 2014	1.0	Jefferson M. Rowley	Initial AppNote
April, 2014	1.1	Jefferson M. Rowley	Formatting updates
July, 2015	1.2	Jefferson M. Rowley	Added/Updated content for Whitepages Pro API v 2.1

Appendix A: RAW JSON Results from Whitepages Pro

We performed a reverse phone number lookup using the following RESTful URL: