Retreaver.js

Retreaver.js is a JavaScript library for displaying and tagging trackable phone numbers. Retreaver.js offers a flexible API so developers can interact with our services in a way that is both straightforward and compliant with modern standards.

Retreaver.js is the preferred method for integrating your site with Retreaver.

Retreaver.js fulfills the following requirements:

  • It can be distributed via CDN.
  • It can be cached by the visitor’s browser.
  • It does not interfere with page loading.

Using Retreaver.js

In order to use Retreaver.js, you’ll need a Retreaver account, and a Campaign set up with either a number pool or static numbers tagged for each trackable attribute combination.

The examples on this page use jQuery 1.11.1, but it’s not required.

Source code

You can find the source for Retreaver.js on Github.

Live Documentation

Complete, automatically updated live documentation is available on our website.

Including Retreaver.js

Insert the Retreaver.js script between the <head></head> tags in your HTML source.

Including jQuery

The examples below use jQuery. jQuery is not a dependency of Retreaver.js but using it will make your life easier.

Displaying a trackable phone number

In the above example, we demonstrate fetching and displaying a number that will get routed directly to Retreaver sales for display on the external pages of the Retreaver website.

Our IVR menu is configured to ask callers what they’re calling about. If they press 1, their call is tagged calling_about:sales and they’re routed to someone who can help them.

By requesting a number that has been pre-tagged with what the caller is calling about, we can route them directly to a salesperson, bypassing the IVR.

To accomplish this, we initialize a Campaign object with the campaign key from our campaign’s page on Retreaver. We then request a number matching the tags we set, and pass in a function that is called when the number is found.

The number is then inserted into a span with id sales-number.

Calling a visitor

You can use Retreaver.js to initiate calls from numbers that belong to a campaign with click-to-call enabled.

Simply call the initiate_call function on a number, with the visitor’s phone number as the first argument, a payload object as the second argument, and a callback function as the final argument.

The visitor will receive a call from the number and will be routed through your campaign like normal. The only difference is that preference is given to the “Click-to-call Greeting” prompt over the normal greeting prompt.

The payload object can include tags as key-value pairs, a target map and checksum, and timer offset and checksum. For more information on click-to-call see the documentation and our programmatic call initiation article.

Tagging a per-visitor number pool number

While your visitor is navigating your site, or filling out a form, you can tag a phone number with relevant information. This functionality is available any time you have a number pool set up on your campaign with per-visitor numbers enabled.

When you enable per-visitor numbers on a number pool, you are telling Retreaver that you want to be able to add tags dynamically after the number has already been matched and displayed to a visitor. As such, we won’t allow any other visitors to see that number while it’s in use.

Setting a mood tag on a number

As an example, you might have a mood field that users on a corporate social networking site can use to set how they feel. As shown in the example above, any time the visitor changes the mood select field, we’ll tag the number with their new mood by calling add_tags on the number.

Retreaver.js HTML Template

Releasing a number pool number

Number pool numbers are constantly pinged once returned from request_number to ensure they aren’t reassigned with different tags.

If you’re using number pools and the number you received is no longer being displayed, you can release it manually by calling the release function on the number. This will stop that number from being pinged.

The number doesn’t need to be released if your visitor is changing pages and the window is being unloaded, it will happen automatically once the timeout seconds on your number pool is reached.

Jason Kay

Jason Kay is the CTO and co-founder of Retreaver.