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 can be included in your page directly or via Google Tag Manager. Note that "tags" in Retreaver refer to key-value pairs of data, while tags in GTM refer to blocks of code/markup.


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.

Source code

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

Live Documentation

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


Automatically replacing phone numbers with trackable Retreaver numbers

There are many ways to integrate using Retreaver.js, depending on what your goals are. For most use-cases, using our simple one line integration will suffice.

  1. Create a campaign, which tells Retreaver how to route & convert your calls.
  2. Configure parameter mappers to detect query string parameters like utm_source and map them to Retreaver tags.
  3. Configure automatic number replacement settings so Retreaver knows which numbers you want replaced with trackable numbers.
  4. Create a number pool for your campaign.
  5. Add the Retreaver.js script to your site via Google Tag Manager or by editing the HTML source.

Getting code to include Retreaver.js

The easiest way to use Retreaver.js is by using the pre-written code that's shown on your Campaign page as seen above.

Simply copy the code and include it in your HTML or add it to Google Tag Manager. You can then configure which numbers get automatically replaced and on which pages, by clicking the "Number Replacement" tab.


The initial number on your page prior to dynamic replacement should be real and reachable. In the event that your number pool is maxed out, or the visitor is using adblock, only the original number will be displayed. We recommend using a static Retreaver number so your calls are still tracked.

View our "Dynamic Number Insertion" guide for more information.


Customizing Retreaver.js for advanced users

We suggest using the starter code shown in the "Adding a Custom Retreaver.js Integration" section of your Campaign page. That code provides a great starting point for moving forward with an advanced Retreaver.js integration.

<script type="text/javascript">
    (function () {
        var scriptElement = document.createElement('script');
        scriptElement.type = 'text/javascript';
        scriptElement.async = true;
        scriptElement.defer = true;
        scriptElement.src = document.location.protocol + '//';
        scriptElement.onload = scriptElement.onreadystatechange = function () {

                host: '',
                prefix: document.location.protocol == 'https:' ? 'https' : 'http'

            // Your code goes here!
            var campaign = new Retreaver.Campaign({campaign_key: 'YOUR_CAMPAIGN_KEY'});

            campaign.request_number(function (number) {
                var link = '<a href="tel:' + number.get('number') + '">' + number.get('formatted_number') + '</a>';
                document.getElementById('phone-number').innerHTML = link;
            // End your code... make sure to add <div id="phone-number"></div> somewhere in the body!
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(scriptElement);

You can find your campaign key at the bottom of your Campaign overview page.

You can also include Retreaver.js directly from our CDN: 

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


jQuery examples

The remaining examples on this page use jQuery 1.12.4, but it's not required to use Retreaver.js. We use jQuery here because so many people are familiar with it.

We suggest using these examples to learn about Retreaver.js functionality, and then implementing the functionality yourself in your preferred style.

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 specific 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 using "Click-to-Call"

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();
visitor_lastname = $('#lastname').val();
campaign.request_number({}, function (retreaver_number){
retreaver_number.initiate_call(visitor_phone_number, {name: visitor_name, lastname: visitor_lastname}, 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.

For a technical example: View our "How to Initiate a Follow-Up Call using Click-To-Call" guide.


Tagging a 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 Visitor Tracking enabled.


Visitor Tracking must be enabled to modify the tags on a number after it has already been displayed. You don't need to enable Visitor Tracking if tags are coming from URL parameters.

When you enable Visitor Tracking 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.


Dynamically setting tags 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.


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.


Real-Time Page Tracking

View our "Real-Time Page Tracking" guide for a complete walk-through on how to enable web tracking capabilities on your landing pages using Retreaver.js.

0 out of 0 found this helpful



Please sign in to leave a comment.