How to Use 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.

<script src="" type="text/javascript"></script>

Including jQuery

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

<script src="" type="text/javascript"></script>

Displaying a trackable phone number

$(document).ready(function () {
    // Configure Retreaver to use the correct API endpoint from your campaign page.
    Retreaver.configure({host: '', prefix: 'https'});

    // Initialize the Retreaver campaign using the campaign key from your campaign page.
    var campaign = new Retreaver.Campaign({ campaign_key: '67d9fb1917ae8f4eaff36831b41788c3' });

    // Set the tags we want to use in order to find a matching number.
    var tags = {calling_about: 'sales', currently_insured: 'no'};

    // Request a number that matches the tags.
    campaign.request_number(tags, function (matching_number) {
        // Insert the number into our page.

        // Save the number so we can reference it later.
        window.retreaver_number = matching_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

function callInitiated(call) {
    alert('The call was initiated with uuid ' + call.uuid);

$('form').on('submit', function () {
    var visitor_phone_number = $('#phone_number').val(),
        visitor_name = $('#name').val();
    retreaver_number.initiate_call(visitor_phone_number, {name: visitor_name, target_map: '1->4166686980', target_map_cs: 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d'}, callInitiated);

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

<script type="text/javascript">
$('select#mood').on('change', function () {
    // Remove any existing mood tags on the number.
    // Tag the number with the new mood.
    retreaver_number.add_tags({mood: $(this).val()});
    <select name="mood" id="mood">
        <option value="happy">Happy</option>
        <option value="sad">Sad</option>
        <option value="angry">Angry</option>
        <option value="inspired">Inspired</option>

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

<!DOCTYPE html>
<html lang="en">
 <meta charset="UTF-8">
//This script is so you can get fields out of the URL to put in variables. UPDATED VERSION THAT ACTUALLY CHECKS FULL PARAMETER NAME BEGIN OF ? OR &
 function getURLParameter(name) {
 return decodeURIComponent((new RegExp('[?|&]' + name + '=' + '([^&;]+?)(&|#|;|$)').exec(||[,""])[1].replace(/\+/g, '%20'))||null;

 <script src="" type="text/javascript"></script>

 var ran = false; //Flag we have not run the script to pull the number yet.
 var loco = ""; //The location of the page that we will load on a second pop.
 var msg = "";

//Figure out what to use for default number and number loaded on subsequent load. Any number from the campaign that is static can be used (or even direct line to client center).
 var default_number = "(888) 222-3333"; //Will be used when number pool is full as the default number. Use Whatever Country Format the number is for.
 var default_plain_number = "8882223333"; //Will be used as the unformatted default number for hyperlinking the number/image/text.
 var number = "(888) 222-3333"; //Use this variable for the formatted number to display.
 var plain_number = "8882223333"; //Use this variable for the hyperlink if used <a href="tel:+1"+ plain_number +"">

//Allow for the traffic source to send in their own default number if a number can't be obtained from the pool.
 var dn = getURLParameter('dn');
 if (dn != '') { //If we going to use a default number different for each affiliate.
 default_plain_number = dn;
 plain_number = dn;
 var dfn = getURLParameter('dfn'); //Get the default formatted number sent in.
 if (dfn == "") dfn = dn; //If no formatted number just use it unformatted.
 default_number = dfn; //So we have it in a good format as well
 number = dfn;

//If we already loaded the page before OR the source is just trying to use a static number at your site.
 var tfn = getURLParameter('tfn'); //Sorry about this variable name. TFN stands for Toll-Free Number, but this isn't necessarily toll-free or even a USA number.
 if (tfn != '') { //If we are reloading the page, don't call the system to get a new number.
 plain_number = tfn;
 var ftfn = getURLParameter('ftfn'); //Get the formatted number sent in.
 if (ftfn == "")
 ftfn = tfn; //If no formatted number, just use it unformatted.
 number = ftfn; //So we have it in a good format as well.

 <script type="text/javascript" defer>
 function loadNumber() {
 if (!ran) { //If we haven't ran this function before, get a new number.
 if (!getURLParameter('tfn')) { //If we don't have the phone number in the URL, get it the first time.
//Initialize the campaign using the campaign key from your campaign page. On the line below, nothing should ever need to change but the key.
 var campaign = new Callpixels.Campaign({campaign_key: '[REPLACE_WITH_RETREAVER_CAMPAIGN_KEY'});

//Set the tags we want to use in order to find a matching number. Format: var tags = {calling_about: 'sales', currently_insured: 'no'}; format is basically var tags = {tag1: 'value1', tag2: 'value2', etc};
 var tags = {lander: 'system'}; //Leave like this if you are not trying to send any tags, or replace with above format.

//Request a number that matches the tags. Format: campaign.request_number(tags, function (matching_number){}, function(error){});
 function (matching_number) {
 number = matching_number.get('formatted_number');
 plain_number = matching_number.get('plain_number');

//Save the number so we can reference it later.
 window.callpixels_number = matching_number;
 }, //end the function (matching_number)
//3rd Parameter of the campaign.request_number function is the error handling.
 function (error) {
 number = default_number; //Since this isn't being returned from function, this is actually a formatted string to use for the default number.
 plain_number = default_plain_number; //This is the unformatted number to be used for hypering linking <a href="tel:+1[plain_number]....
 } //End the error function.
 ); //End the campaign.request_number function.
 } //End if reloading.

 ran = true; //So we don't get the number more than once.
 var loco_params = "?tfn=" + plain_number + "&ftfn=" + number + ""; //On a reload, the script looks for the tfn variable and will not call the script to get a new number again.
 loco = window.location.hostname+window.location.pathname+loco_params;
//If you wish to use a wildcard subdomain on the reload, uncomment the line below.
//Wildcard subdomains are configured by setting an A Record in your DNS Zone to the same IP address as the main domain A Record (some other server config may be required).
// loco = Math.floor((Math.random()*1000000)+1) + loco;
 // ***********************************************************************************************************
 // do any variable replacements in the html or alerts here and calls to any alert functions that may be needed
 // ***********************************************************************************************************
 } //End the if Not Ran check.
 } //End the loadNumber function.

<body onload="loadNumber();">

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.

0 out of 0 found this helpful



Please sign in to leave a comment.