Click-to-Call: Programmatic Call Initiation

Introduction to click-to-call

Using Click-to-Call, web visitors may initiate calls from your web page with just the click of a button. These calls can be initiated using Retreaver numbers that are currently being displayed on your landing pages, or they can be initiated via a server-to-server request.

Click-to-Call works by gathering various attributes from your webpage, including present URL parameters on your page, form submissions and any other on-page events when used in conjunction with Real-Time Page Tracking. You can pass in unlimited tag values to associate with the call in your click-to-call initiation request. As leads submit their phone number on your form, the Retreaver script on your page will package all gathered attributes and programmatically initiates a call to your desired campaign using a Retreaver number of your choice.

This is a great way to increase conversions as it ensures your visitors get on the phone with ease, directly connecting them to the most applicable call endpoint suited to process them.

Note: Click-to-call is different from tap-to-call, which is just using tel links to link a caller to a phone number on your page using HTML. The advantage of Click-to-call is the additional data you can associate with a inbound caller prior to connecting with a campaign.



Click-To-Call Guide Overview


Getting Started: Setting up your campaign

Getting Started: Setting up your campaign

In order to use click-to-call, you must first enable it for your campaign. Browse to your campaign and click the Toggles tab, then enable the click-to-call toggle.

Clicktocall.png Enabling click-to-call on a campaign. 

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

Initiating calls server-to-server

Retreaver users can use the Retreaver API to initiate calls by sending a JSON-formatted POST request to:[number_id].json

Finding your Number ID


Select a number from your numbers page to view your number overview page, where you will find the Number ID for that particular tracking number.

Replace [number_id] with the ID of the Retreaver number you want the call to come from.

You must include a dial attribute in the request body, this tells us which number you want initiate a call for. You can also include any additional attributes you want associated with the call as tags using the "key:value" syntax. You can use any attribute names other than reserved keywords.

Example of a JSON-formatted POST request:

> 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 will be returned to you upon the successful initiation of a call and can be used via our API to get more information about the result of the call, or to reference the call in the future.

If the request was not successful, an error 500 will be returned. This could occur if no dial attribute was provided with the request.

Initiating calls through the browser

Initiating calls through the browser

You can programmatically trigger a call using the Retreaver.js script placed on your webpage, provided that a dial-able phone number is present and that there is a publisher matching number available to initialize the call.

Calling a visitor Script Demonstration

//Include jQuery library to handle form submission events above Retreaver Script
<script src=""></script>

//Modify the noConflict attribute If you are working with frameworks utilizing the "$" operator
//Then replace all instances of "$" with "jQuery_latest" instead to prevent overiding the operator

<script type="text/javascript">
var jQuery_latest = $.noConflict(true);

callInitiated(call) { alert('The call was initiated with uuid ' + call.uuid); }
//Form element contains an ID of "form": <form id="form" action="#">
//Form button contains a type/value of "submit": <button type="submit" value="submit">Call Me</button>

$('#form').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.

You may also view the "How to initiate a Follow-Up Call" legacy guide for more reference material.

Crediting the correct Publisher/Source

Crediting the correct Publisher/Source

You can associate a publisher to a particular number when editing the number under the publisher field:


For server-to-server requests, we'll automatically attribute the call to the publisher associated with the number_id used to initiate a call.

For browser-initiated requests, we'll automatically attribute the call to the publisher associated with the currently displayed number on the page.

If there is no publisher associated with the number that you wish to use, you can pass an affiliate_id along with your Click-to-Call request. 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, this way you can avoid creating a separate number for each Publisher.

Influencing which endpoint we route the call to

Influencing which endpoint 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 presently associated with a routing setting on your campaign.

When supplying additional attributes in the parameters of a click-to-call initiation, include your desired attribute name in "key:value" syntax as an argument. These tag based attributes can then be used to influence the routing decision for any inbound calls made to that campaign.

You can include call tags 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.