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

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

> 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

You can programmatically trigger a call via our Retreaver.js script if there is a Retreaver number displayed to the visitor and you know their phone 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();
visitor_lastname = $('#lastname').val();
campaign.request_number({}, function (retreaver_number){
retreaver_number.initiate_call(visitor_phone_number, {name: visitor_name, lastname: visitor_lastname}, callInitiated);
}) })

To learn more about initiating calls via Retreaver.js, please visit our guide on Retreaver.js - Calling a visitor.

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

Crediting the correct 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 Retreaver routes to using our tag-based routing feature.

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.

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.

0 out of 0 found this helpful



Please sign in to leave a comment.