Programmatic Call Initiation

Follow

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.png

Enabling click-to-call on a campaign. 

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.

> HTTP POST
> https://retreaver.com/calls/new/for_number/3459.json
> Content-Type: application/json
{"dial": "4166686980", "first_name": "Jason", "last_name": "Kay", "school": "Harvard"}

< HTTP/1.1 200 OK
< Connection: close
< X-UA-Compatible: IE=Edge
< Content-Type: application/json; charset=utf-8
< X-Request-Id: 8ef2627d7e29b4bf581042245e8eeca9
< X-Runtime: 1.671368
< Cache-Control: max-age=0, private, must-revalidate
< Etag: "b0f55d8a11096940dd48e470bba4d247"
< Content-Type: application/json; charset=utf-8
{"status": "initiated", "uuid": "e46458ee-d89d-4a37-8dbf-ab08c0b97d0c"}

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

Please Note

This documentation is for the deprecated insert.js. To initiate calls via Retreaver.js, please visit our guide on 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.

<script src="https://retreaver.com/insert.js?key=99ff9929ee38c461302712ae37c43e69&default_number=&ref=capital-one" type="text/javascript"></script>

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.

retreaver.call(phone_number, number_ref, parameters, callback);
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/Source

When the code says 'affiliate', it is referring to your Publisher/Source.

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.

retreaver.call("+14166686980", {"buyer": "capital-one"}, callbackFunction);

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:

retreaver.call("+17195220377", {"target_map": "1->4166686980", " target_map_cs": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"}, callbackFunction);

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
require 'ruby-hmac'
target_map = '1->14012979428'
api_key = '' # Your api key
puts Digest::SHA1.hexdigest("#{target_map}#{api_key}")
PHP
$string = '1->14012979428';
$api_key = ''; // Your api key
echo sha1($string . $api_key);
Python
import hashlib
target_map = "1->14012979428"
api_key = "" # Your api key
m = hashlib.sha1()
m.update(target_map + api_key)
print m.hexdigest()

Reserved keywords

action
afid
c
controller
cpAFID
cpSID
default_number
dial
ga
key
message
number_id
ref
show_key
sid
st
target_map
target_map_cs
timer_offset
timer_offset_cs
u
uuid
value
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.