Click-to-Call: Programmatic Call Initiation

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.

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

Retreaver users can use the Retreaver API to initiate calls by sending a JSON-formatted POST request to:
https://retreaver.com/calls/new/for_number/[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:

> HTTP POST
> https://retreaver.com/calls/new/for_number/13579.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 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

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="https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js"></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);
</script>

function 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

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

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.