Programmatic Call Initiation

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

Clicktocall
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: https://retreaver.com/calls/new/for_number/[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

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 retreaver.call function.

phone_number
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!

Ruby

PHP

Python

Reserved keywords

Jason Kay

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