Retreaver Tracking URLs are now Webhooks

August 1, 2018 | Jason Kay

Today we are pleased to announce that Retreaver Tracking URLs are now called Webhooks. While the functionality remains the same, this update necessarily acknowledges the evolution of how Retreaver customers, new and old, are integrating their call data with other web-based services and platforms in new and exciting ways.

The History of Tracking URLs in Retreaver

Retreaver first launched as CallPixels in 2012 as a call tracking platform for marketers. It allowed phone call outcomes to trigger pixels fires for the purpose of tracking call conversions. Retreaver delivered conversion tracking for phone calls the same way that tracking pixels were doing (and are still doing) for websites and landing pages, and like for those pages, “Call Pixels” were added to call campaigns using Tracking URLs.

Your Calls Now Drive More Than Tracking

By 2016 Retreaver customers were doing much more with call data than ever before. A change in company name to Retreaver saw a new emphasis on tagging calls with data, and tracking and routing calls with that data.

Retreaver Tracking URLs are no longer just for when agents answer or for when calls end. They are now being triggered when calls are dialed by consumers when agents are selected when they are connected and still when the call ends based on conversion outcome. It’s functionality that has created countless possibilities for companies looking to integrate inbound calls with their digital marketing workflows and services.

Use Retreaver Webhooks To Make Workflows Seamless

Retreaver Webhooks provide you with the ability to POST or GET with any system. Passing data right within URL parameters on those webhooks.

With this capability to send any of your call data to other systems, and to receive information back onto calls in real-time, Retreaver makes it possible to have your calls work with services such as:

  • Google Analytics 360 – Send information about your calls to Google Analytics including Valuetrack parameters from ads, custom dimensions, campaign details, even the answering agent. And capture this for each stage of the call. Read more here.
  • ClickSend – Send your agents answering the phone a visual heads by up using ClickSend text messages right before they answer the phone. Follow up with callers that have opted-in with text-message-based offers and thank you messages.
  • Zapier – Get inspiration about what’s possible by using Zapier to leverage the power of 800+ online services. Send our call data to Zapier to integrate workflows with most marketing and online services and return data to your calls for use in routing.

To learn more about how Retreaver Webhooks can help you to Do More With Call Data™, send us a message at or call 1-866-898-7878.

How to find a HubSpot Owner ID

February 14, 2018 | Jason Kay

A HubSpot Engagement

A HubSpot Engagement

Retreaver can create Engagements in HubSpot each time a call is received, which have information about the call including recording, duration, etc. These engagements are associated with a HubSpot Owner or salesperson.

This allows you to treat callers who are already in your HubSpot account specially, for instance, routing known callers directly to their HubSpot Owner or salesperson.

Finding a HubSpot Owner ID

Finding your HubSpot Owner ID

Finding your HubSpot Owner ID

To find your HubSpot Owner IDs, click Settings in the main menu in HubSpot, then Properties from the menu on the left. Then enter “HubSpot owner” in the search bar under Contact properties. Click view next to “HubSpot owner”.

At the bottom of the next page, your HubSpot Owner IDs are listed in the “Dropdown options” table in the “Internal Value” column.

Set your Call Endpoint in Retreaver to have the same ID and we’ll automatically create a HubSpot engagement for each call to that Call Endpoint.

You can set a default HubSpot Owner to be used when an unknown caller calls in and is routed to a Call Endpoint that isn’t associated with any specific salesperson, like your call center’s main line. We suggest setting up a “Retreaver” or “Bot” user in HubSpot, and setting the default Owner ID on your Retreaver Integration.

Interfacing to Adwords

August 1, 2016 | Jason Kay

Route AdWords Calls Based on Search Keyword or Ad

When promoting your website using Google Adwords, sometimes you want to ensure that calls for certain keyword searches or ads get routed to the correct destination. This is easy to do using Google’s ValueTrack parameters and Retreaver number pools.

Setting up your AdWords campaign

Passing the creative and keyword to a landing page.
Configuring an AdWords ad to pass the creative and keyword to a landing page.

Edit your Google AdWords ad’s destination URL to include the ValueTrack parameters that you want to route on. In the example above, we’re passing in the creative ID as ga_creative and the keyword as ga_keyword.

Configure your campaign’s number display script


Adding Tags in Retreaver (left) to detect from the landing page URL (right).

View your campaign, and select the Settings tab from the Dynamic Number Insertion section. Here you will configure how Retreaver should detect the ValueTrack parameters that you are now passing to your landing page. As shown above, whenever a visitor clicks through to your page via one of your AdWords ads, we’ll attempt to detect the values of the ga_keyword and ga_creative tags.

You’ll need to have a Number Pool configured for your campaign in order to use this feature. Because we are tagging numbers dynamically as visitors reach your landing page, you might need a large number pool depending on the number of unique keyword/ad combinations that you want to track, but limited to the number of concurrent visitors you expect.

Once the visitor calls the number that is displayed, we automatically Tag the call with the Google AdWords tags that have been set on the number.

Tagging your Buyers with your Google Adwords Tags

Enabling the Id column in Google Adwords.
In order to get the creative ID that will be passed to our landing page, we need to enable the Id column in AdWords.

Now that we are passing the creative ID and search keyword to our landing page and detecting it in Retreaver, we need to tag the Buyers on our campaign. You can retrieve the AdWords creative Id for your ads by following the instructions above.

Adding a Google Adwords creative Tag to a Buyer.

Edit the Buyer you want to tag, and add the tags to the tag list. In our case, we’ve tagged a Buyer with ga_creative:17394206701 because we have a special ad that’s promoting Google AdWords call tracking and we want to be sure the we know what the caller is calling about. To do this, we’ve also added a bridged ping tracking URL to our campaign, informing our operator that the caller is calling about AdWords. If you have only one Buyer tagged with the tag, you can add a bridged ping tracking URL which is tagged with the ga_creative tag instead of the buyer_id tag, it’s up to you.

Routing Based on Traffic Source

Sometimes you have high-value traffic that you want to ensure only gets to your best call buyers, or sales representatives. Perhaps you have a Google Adwords campaign running and you want to make sure calls from that campaign are treated specially. Add any parameters you want Retreaver to sniff for by editing your Default URL Parameter Sniffing as outlined in this article.

Next, we configure the Retreaver.js script to detect the source parameter in the landing page URL. You’ll need to have the script somewhere on your landing page for this detection to happen. Navigate to your campaign and click the Settings tab in the Dynamic Number Insertion section.

Enter source as the tag key and URL parameter, and update the campaign. Now whenever someone visits your site, we’ll automatically check the landing page URL for the source parameter, and set the source tag if it is found. For this to happen, you’ll need to have either a Number Pool configured for your campaign, or numbers configured and tagged individually with each possible source tag that you want to use.


Adding a source tag to a Buyer.

Finally we add the source:ga tag to our Buyer, ensuring that any Google Adwords calls get routed to it only. Perhaps they are specially trained on handling calls from your AdWords campaign, or it’s a buyer that pays you more for these high-value calls.

Call-Only Ads

The only way to pass keywords into Retreaver from Adwords Call-Only ads is to set up a static phone number in Retreaver tagged with each keyword, and then in Adwords set up a corresponding Ad Group using that phone number and that single keyword.

Click here to view an example.

This has potential to be somewhat tedious. Feel free to contact for assistance setting it up.

We would also love to know how you’re using it and what needs Retreaver is filling. Knowing this would go a long way toward helping us automate using Google’s Adwords API.


March 15, 2016 | Angela Dougherty

URL Parameter Sniffing

Retreaver can pick anything up from the URL, but you need to tell it what to look for, and what it’s called in the system. For example, you don’t want anyone to know who drives your traffic, so you would sniff for a to resolve the affiliate_id.

The Dynamic Number Insertion section on your Campaign screen.

Tracking keywords becomes easy when you can just send it to us in the URL. We can then sniff for them and filter calls to your buyers using these fields.

We recommend these articles to help understand how Retreaver functions: Learn what Tags are, then learn about how a call gets Tagged, then learn how to filter calls to your Buyers with these Tags.


An alternative to Insert.js is our more robust Retreaver.js is our JavaScript library for displaying trackable phone numbers, it offers a flexible API so developers can interact with our services in a way that is both straightforward and compliant with modern standards. It is able to be cached by the visitors browser, and quickly distributed via a CDN.

More info on Retreaver.js

If you run low volume traffic and do not require alerts, this guide on our much simpler Insert.js will fulfill your needs.


Our script without &message= will only show the number and not hyperlink it. To hyperlink, you just take what would be the JavaScript to hyperlink a number, image, text, or a button and put that in the &message={URL Encoded JavaScript}.
We then replace the JavaScript call to us with the formatted JavaScript you put in &message=.

No Hyperlink

(Do not include &message= in the script)

src=”{Insert Campaign Key Here}&default_number=%2B{Insert Phone with Country Code Here}” type=”text/javascript”></script>

Hyperlinking an Image, Text, Phone Number, or Button

(Setting &message= for different functionality)

Image: <a href=”tel:+1[plain_number]”><img src=”{Path To Image}”></a>

Text: <a href=”tel:+1[plain_number]”>{Text To Be Hyperlinked}</a>

Formatted Number: <a href=”tel:+1[plain_number]”>[number]</a>

Button: The hyperlink part will look like <a href=tel:+1[plain_number] class=”button”>, then the rest of the format for Image, Text, or Formatted Number.
You will take from <a to </a> and URL Encode it, and that is what the &message= is set to.

We find this tool helpful in encoding and decoding URLs:

Click Here For Hyperlink Code Examples

Final Script

<script src=”{Insert Campaign Key Here}&default_number=%2B{Insert Default Phone With Country Code Here}&message={URL Encoded HyperLink Javascript Code}” type=”text/javascript”></script>


Interfacing to HasOffers

| Angela Dougherty


In order for HasOffers to interface to Retreaver using goals, the offer should be set up with a conversion pixel of Server Postback w/ Affiliate ID. Goals should also be enabled in HasOffers.

Configuring your Pay Per Call Offer this way allows you to track Publisher payout to the main conversion. Then revenue to the goals that are set up for each buyer. The HasOffers goals have been designed to allow for a different advertiser on each goal. The conversion pixel type on the goals should also be set to Server Postback w/ Affiliate ID.
The following four steps will help you understand how HasOffers interfaces with Retreaver.

Step 1: Create the offer in HasOffers


Step 2: Create a Goal for each Buyer in HasOffers


Step 2 Results: Goal for Main Offer and Each Buyer in HasOffers


Step 3: Cross reference Goal with Buyer ID

Click View on the Goal Options in HasOffers to see the conversion pixel. Use the goal_is from the pixel as your Buyer ID in Retreaver.

Step 4: Tracking URL set up in the Campaign on Retreaver

NOTE: The tracking URL for the revenue has &goal_id=[buyer_id]

NOTE: In the screenshot below in the tracking links you will see it says [affiliate_id] this value has changed in Retreaver to [publisher_id]


Interfacing to Voluum

February 20, 2016 | Angela Dougherty


Voluum is one of the most robust tracking systems available to help you optimize your lead spends. However, if you try to track calls to Voluum using a clickid, you would need enough numbers to track all your concurrent visitors since each visitor would need a unique number to tag the number with the unique clickid. The following documentation is an alternative way to still use Voluum, but only track the information that is important to you, and not down to a clickid. You could also do this for or a variety of other tracking systems.

Using a tracking system like Voluum you could even have your Google Adwords go through Voluum and only track what you want to track. If you use Google Analytics integration with Retreaver, you are stuck with having a number pool big enough to track visitors with a unique phone number, which is fine for low volume campaigns, but not very good for high traffic campaigns.

Retreaver can interface to Voluum in two ways. By Server to Server using a ClickID, and by Cookie Based Pixels only tracking the relevant information you need from each traffic source to optimize. It is suggested you use the Cookie Based Method instead of S2S so that your number pool sized can be managed better, and the tracking will be more accurate.

New to Voluum? It would help us out here at Retreaver if you used this referral link when you sign up for Voluum:

Cookie Based Tracking

When optimizing, send fewer fields to your landing page from Voluum, and then add more fields to track as you refine the broader sources. For example, On, you could bid on 500 Sources and all their Sub Sources. You will be sending both of the values on the click to Voluum to track; however, if you only send in the Source to the landing page initially, you can figure out which sources to bid on and which to eliminate, before you start sending the Sub Source to the lander to refine the Source’s traffic by Sub Source.

Traffic Sources

In the below images, you can see that every Traffic Source setup in Voluum has been given some custom token names that will be used to track the important information that you would like posted to Voluum.

No matter what traffic source you are getting the traffic from, it is best to come up with a naming standard for the fields you want to track from each Traffic Source. In this example, we have used r_src through r_src5 meaning retreaver_tracked_source. Custom Tokens:

Redirect Tokens

1. This is where Voluum will look in the url to find the custom token to extract.
The replacement tokens for this column are {var1} thru {var10} based on the order listed in this column.

2. This is how the Traffic Source denotes the token name for replacement in their system.
Note: Delimiters for tokens vary by traffic source, most use {tokenname}, but as shown above redirect uses #tokenname#, LinkTrust uses [=tokenname=], and even Retreaver uses [tokenname]. See the help section in the traffic source for how they delimit tokens for replacements in strings.

3. This is the name of the field to be shown on Voluum reporting.
You can name it what the traffic source calls it or however you want to see these fields on Voluum reporting. If you want to use this column for token replacement it is {var:fieldname}.

4. This is just a flag to indicate if the field should be included on the Voluum Reporting for this Traffic Source or not.

5. The variable r_buyer denotes the Retreaver Buyer of the call. We have to define it for each Traffic Source so that Voluum has it as a custom field, but you would not fill in the Placeholder since you will not be getting this field from the Traffic Source; but rather, from Retreaver after the call is complete.

50onRed Custom Tokens:


MediaHub Custom Tokens:

mediahub tokens

ZeroPark Custom Tokens:

zeropark tokens

Of course these traffic sources may have many more tokens you want to track, Retreaver calls these Tags. There can be many more sources you have. Contact Support if you have a Traffic Source you do not know how to define the Advanced Settings in the Traffic Source for.

Setting up an Offer and Campaign on Voluum

There are many ways to get the traffic to the final landing page via Voluum. However, for this example, we are only going to create an Offer and combine it with a Traffic Source in the Campaign.

Step 1: Offer Setup

Pictured below is the Voluum Offer Edit Screen:



System tokens in Voluum are defined as {tokenname}, while user defined tokens are {var1 thru var10} if doing based on column 1 names of the Tracking Source Custom Variables OR {var:tokenname} if using the name in the 3rd column.

All of the query string variables are optional. Query string are all the data after the ? in the URL. However, if you follow these standards to send to each lander, we can use a standard pixel in the tracking URL of all the Retreaver Campaigns.

In this example, we are only sending os, browser, isp, and ip to the landing page so we may use this information for display variables on the page. Variables r_src through r_src5 are sent as whatever values we received from the Traffic Source. Variable vcid is the Voluum Campaign ID; Retreaver will pick this up as a Tag for the postback URL. The last two fields named dfn (Default Formatted Number) and dn (Default Number) are used so that you can have many campaigns from Voluum, but land on the same landing page. By sending in the dfn and dn fields, you will be able to have a unique default number to use if the Number Pool definition in Retreaver is too small.

URLs must be Encoded when placing them in Voluum.  In the URL example %20 is the <space> between the Area Code and Preifx, and %2B in the dn field is the plus sign (+).

Step 2: Voluum Campaign Setup

Pictured below is an example of the Campaign Setup In Voluum:


1. Campaign URL to be placed on the system to send traffic through Voluum:

Note that it is adding the query string fields from the Traffic Source Advanced Settings. A different traffic source would have different tokens appended.

2. You can combine any traffic source you want with the same offer.

3. The offer has the URL that points to the landing page in this example.

Step 3: Setting up the Campaign on Retreaver

Although you would normally set up campaigns on Voluum separately for each Traffic Source, in Retreaver that would require extra numbers to be used since the Number Pools are defined by Campaign. It is highly recommended that you just use one Campaign per vertical, and let our tags do the reporting for you.

Here we are only focused on the Tracking URLs to interface to Voluum with data instead of by clickid. Our dedicated support staff are here to help you configure your tracking interface with Voluum or help configure your campaign, contact us at and be sure to have your tracking URL from Voluum handy.


Configuring tokens within your tracking URL. Note that in the above image, target_id has since changed to buyer_id.

You may have noticed that the landing page url placed on Voluum had &vcid={}. This is how we will be able to interface back to Voluum which will have many campaigns, but only have one campaign setup in Retreaver.

  1. Tracking URL to do a Click in order to write a cookie to the Retreaver servers, for the pixel that fires below:[vcid]?r_src=[r_src]&r_src2=[r_src2]&r_src3=[r_src3]&r_src4=[r_src4]&r_src5=[r_src5]&r_buyer=[buyer_id]&tfn=pixel You can send in [buyer_id] if you have used that field in the Buyer Edits, or [system_buyer_id] if you haven’t. We are sending &tfn=pixel only to tell the code on the landing page, that this is a Retreaver click for the postback, and the lander does not need to try and generate a lead.
  2. Pixel URL:[revenue]&txid=[call_uuid]

Example Default Number to be used for Campaign

Redirect number overview

We add two tags to each static number we have to pull manually from the system for each campaign that is running. This will allow us to still track that we have a call back to Voluum; however, we identify that the number pool was full and the default number had to be used:

  • vcid is set to the campaign id from Voluum
  • r_src is set to whatever you want to show in Voluum reporting that these calls aren’t actually tracking the source of the call on the campaign.

Setting up the Campaign Settings on Retreaver

There are two ways to tell Retreaver what you want to track from the landing page URL:

1. In the campaign settings you modify what you want us to track from the URL and what Retreaver Tag to place it in.

2. Have the Retreaver campaign look for all the possible tags you want to track, but as you optimize, modify how much information you actually send to the landing page in the URL.

Option 2 is going to make much more sense, since we are trying to optimize many campaigns in Voluum to only one campaign in Retreaver.  As mentioned in the beginning of this article, the best way to optimize is start with tags that are not very unique, and then as you decide which ones of those are working well enough to refine more, add them to the landing page URL in Voluum on the campaign.

Sniffing Voluum

Note that if you are trying to send an publisher_id to Retreaver, it must exist in Retreaver to populate the tag. In the example above the voluum landing page URL has &a={}. This assumes that you have named your traffic sources with the same value as the publisher ID in Retreaver. Since campaigns in Voluum are linked to traffic sources, you could also hard code this to be &a=RD. RD being the publisher ID you have given in Retreaver.

Suggested Optimization Strategy

The suggestion we make as you optimize a campaign (now that you are not tracking by clickID) is to only send broad information to the landing page, and then as you can narrow your bids on the broad tag values, do more refined tracking. example: Since you won’t know what Sources to bid on from when you start, do a broad bid but only send the Source to the landing page. Even though you get the Subsource from Redirect to Voluum, initially don’t send it to the landing page. Once you have narrowed down what Sources are making calls happen, you then only bid on those Sources, and start sending the SubSource to the landing page. In the flow of this document that would be r_src={var1} initially, then add in r_src2={var2}.

This same logic can be used for any Tracking Source.  Send all the information from the Tracking Source to Voluum, but control what you want Retreaver to track by only sending limited information to the landing page originally and adding more information as you refine the bids.

Server to Server Tracking by Click ID

With Voluum’s clickid postback, the clickid has all the information about the click, siteid, browser, browserversion, os, osversion etc. So you can send us the clickid, and we post that back to Voluum and they will provide your reporting. Voluum’s reporting gives much more insight on your tracking as well as a great place to optimize the keywords and zones that work.

You need to host up a modified landing page, which we can of course help you with should you need it. Then you configure your Voluum to send similar to what is below.{clickid}

You must include: &clickid={clickid}

You can optionally send:

&os={os} You can filter calls to Buyers using this field.
&etc etc from voluum tags

If you are not trying to track back to anything and just use our reporting, then pass zoneid and placementid to Voluum or bypass them. Then send to us and don’t try to postback to Voluum. We can track anything you send to us.

Note: The Postback URL after the call completes needs UUID, key and CallID.

If you simply want to see what source is bringing traffic for calls, you can just track that with Retreaver.

Interfacing to CAKE

| Angela Dougherty

CAKE logo

Below is some information on interfacing to CAKE, however we suggest you contact us at and include your tracking URL and what a conversion pixel looks like for us to help you set it up correctly. The Retreaver Team is here to help you interface to any external tracking system you ever need.

How to configure your CAKE Tracking URL.

When configured, you will simply have a click if it doesn’t convert and a click and conversion if it does. That’s the magic of Retreaver.

Matching IDs

Publisher ID matches Affiliate_ID with CAKE.
Campaign ID matches Offer ID with CAKE.
Buyer ID matches Buyer ID with CAKE.

If you are doing lead-gen in CAKE, you will only need the Buyer ID to match.


August 13, 2014 | Jason Kay

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.

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.

Programmatic Call Initiation

July 1, 2014 | Jason Kay

Introduction to click-to-call

With Retreaver, you can initiate calls for your web visitors without any interaction on their part. These calls can be tied to their existing Retreaver session and any numbers that are being displayed on your landing pages, or they can be initiated via a server-to-server request.

Click-to-call can be used instead of choosing to display a trackable phone number to your visitors. Click-to-call works by collecting your visitor’s phone number and initiating a call to them programmatically. This is a great way to increase conversions, as it ensures your visitors get on the phone.

Click-to-call is perfect for users who want to track many different attributes, but don’t want to create large number pools. You can pass in unlimited tag values to associate with the call in your click-to-call initiation request.

Note: Click-to-call is different from tap-to-call, which is just using tel links to link a caller to a phone number.

Getting Started

Setting up your Campaign

Enabling click-to-call on a campaign. Click the image above to expand in size.

Once you decide to use click-to-call, you need to enable it on your campaign. Browse to your campaign and click the Toggles tab, then enable the click-to-call toggle.

Setting up Numbers

You must have at least one number associated with the campaign to use click-to-call. This number will be displayed on the visitor’s caller ID. If the person misses your call and calls back, they will still be routed to the proper Buyer as their new call will take on the properties of the missed call.

Initiating calls server-to-server

Send a JSON-formatted POST request to:[number_id].json
Replace [number_id] with the ID of the Retreaver number you want the call to come from.

In the request body, include a dial attribute that tells us which number you want us to call. You can also include any data you want associated with the call. You can use any attribute names other than reserved keywords.

The call UUID is returned to you and can be used via our API to get more information about the call, and to reference the call in the future.

If the request was not successful, error 500 will be returned.

This uses the same interface that our number display script uses to place calls through the browser.

Initiating calls through the browser

This documentation is for the deprecated insert.js. To initiate calls via Retreaver.js, see Retreaver.js – Calling a visitor.

You can programmatically trigger a call via our insert.js script if there is a Retreaver number displayed to the visitor and you know their phone number.

If you have more than one number displayed on a page, you must pass a ref parameter in the query string of the insert.js script. You can then use the value of this ref parameter to reference the number that we return.

In this case, you could also add a ref:capital-one tag to the Buyer that you want the call to be routed to if you also have multiple Buyers on the campaign.

To initiate a call, simply call the function.

The string phone number you want to dial to reach the consumer.
number_ref [optional]
The string ref value of the number you want to use to call the consumer, if you’re displaying multiple numbers on a page. This helps our script understand which number it should be using to place the call.
parameters [optional]
A JavaScript object with additional parameters to pass to Retreaver. This can include key:value pairs for tags, or any other data you want to use in the call. All of these additional parameters are available for use in our tracking URLs as replacement tokens.
callback [optional]
A callback function which will receive the result of the request to Retreaver, including the call UUID and status.

Crediting the correct Publisher

When the code says ‘affiliate’, it is referring to your Publisher.

For browser-initiated requests, we’ll automatically attribute the call to the Publisher associated with the displayed number.

If there is no Publisher associated with the number you wish to use to initiate a click-to-call call, you can pass an affiliate_id in. Pass the affiliate_id attribute in via the parameters field of your JavaScript function call, or in the body of your server-to-server POST.

In this way, you can avoid creating a separate number for each Publisher.

Influencing which Buyer we route the call to

You can influence which Buyer we route to by using our tag-based routing feature, or by using placeholder buyers/target maps.

When the code says ‘target’, it is referring to your Buyer.

Tag-based routing

Tag-based routing can be used to route the call to a Buyer that is already associated with a routing setting on the campaign.

If you’re using our number display script, we highly recommend that you make use of the ref tag to tag your Buyers, since that parameter is also needed if you’re displaying multiple Buyers on a page.

Otherwise, simply create a new tag without a prompt in Retreaver. You might call this new tag buyer.

In the parameters for the click-to-call initiation, include the tag key and value as an argument. You can include this in the body of your server-to-server request or in the parameters argument of your Javascript function call.

The call that’s created will be automatically tagged with target:capital-one. On a campaign without any prompts, the call will be routed directly to a Buyer in the “when 1 is pressed” scenario which is tagged withtarget:capital-one.

Secure Override: Buyer map

Placeholder Buyers are useful when you don’t know the number of the Buyer in advance, or when you can’t add all the Buyers to your Retreaver campaign.

You can configure your campaign with a placeholder Buyer and use our Secure Override feature to dynamically swap in a new Buyer number. To create a placeholder Buyer, simply create a new Buyer with a number ranging from 1 to 99.

Secure Override requires that you pass in two arguments with your click-to-call parameters: target_map in format original_target_number->new_target_number, and a checksum attribute named target_map_cs as described below.

If I have a placeholder Buyer with number 1 which I wish to map to 416-668-6980, my Javascript function call would look like this:

Calculating the target_map_cs checksum

We need to calculate the SHA1 hex digest of your target_map string joined with your API key. You can get your API key by clicking here.

Your API key should never be included in your web page’s source code or exposed to your visitors as it grants unfettered access to your Retreaver account!




Reserved keywords

Retreaver Results

June 14, 2014 | Jason Kay

For most lead generators, inbound sales calls are distributed to buyers on a 1-to-1 basis. Each caller is routed to a single buyer. But what if you could allow consumers to call all your buyers?

Introducing Retreaver Results

Retreaver Results is a new API that facilitates the display of individual trackable phone numbers for each Buyer on a campaign. The new Results functionality allows consumers to comparison shop, delivering fully qualified leads to multiple buyers.

Click Here to View our Demo Site

Retreaver Results follows all your existing business logic on Buyers, like business hours, caps, and tag filters. Ask your visitors for their zip code, and pass that information along to the results.js script to filter Buyers by geo. Any tags that can be used in the Retreaver system can be passed to Retreaver Results to determine the Buyers you want displayed.

Once the visitor dials in, they’ll be routed directly to the Buyers they chose, without any unnecessary IVR prompts.

Getting started

The results.js code. The show_key is specific to your campaign, retrieve it form your campaign page.

Simply add the results.js code to your thank you page, and append any tags you want to pass in via the query string. Above, we pass in the consumer’s zip code as 90210 so we only show Buyers that can take calls from their area.

For each Buyer you want to display, create a <div> element with ID matching cp-target-3410 where 3410 is the Retreaver system Buyer ID. You should wrap all the Buyer divs in a single parent div element. We’ll dynamically hide and re-arrange the cp-target divs depending on which Buyers can receive a call from the consumer, and with respect to your priority and weight settings.

If you’re using Buyer groups and you only want to show one entry per group, you can add a <div> element with ID matching cp-target-group-501 where 501 is the Buyer group ID. When a visitor calls the displayed number, they’ll be routed as normal to one of your grouped Buyers. This is useful when you have multiple Buyers for the same company, each with different hours of operation.

Like with our number display script, use replacement tokens [number] and [plain_number] within each cp-target div to insert the formatted phone number and unformatted phone digits of the trackable number.

We’ll only display the buyers that match your visitor, and that are open and able to receive a phone call.

You can put any content you want in the Buyer/target divs, like a logo, the name of the buyer, and a description. We’ll only display the Buyers that match and are open and able to receive a phone call. Set the divs as hidden by default to make sure they don’t “flash” while the display script is executing.

If you’re passing in arbitrary tags like zip-code tags, you’ll need to have a number pool configured for the campaign so that we can dynamically assign phone numbers for the visitor to call.

No matching Buyers

When there’s no Buyer that can serve the visitor, we enable the display of div with ID cp-targets-none. This div will be hidden if there are Buyers displayed.

jQuery integration

When we’re done processing the results and Buyers have been displayed, we fire event cp-results-processed on $(document).

Demo App
Our demonstration implementation, a lead-gen form for auto insurance.

View our demo app at This app features the option of choosing between click-to-call or Retreaver Results.

The code for this site is open source. Take it and use it in your own project.

Consumers enter their zip code and the results are automatically limited to the given geo. All calls are automatically tagged with whether or not the visitor already has insurance, and this information is passed to the Buyer via a whisper prompt.

The code for this site is freely available as a Ruby on Rails app, which can be easily adapted to suit your needs. Please fork the project and send us a pull request with your improvements. We’re looking forward to seeing your Results!