NAV
Developers
Javascript

Javascript API

Our documentation to help you customize CallPage to fit your website

We offer a powerful Javascript API that gives you flexibility and control over the behavior of the CallPage window. You can decide, how, when and where to display the window on your site, as well as view and update visitor information.

  1. Make sure you have the latest CallPage embed code.
  2. For callpage API calls, place them in code after CallPage embed code.

We encourage developers to write their own Javascript to extend the CallPage functionality on their sites. We’re very excited when we see examples of the API used in creative ways. Let us know if you have an interesting implementation and we may publish it.

Email andrew.tkachiv@callpage.io with your creations!

Testing and Debugging

The API is intended to be self-serve. Although we can’t debug or write JavaScript for you, there are some helpful ways to test your own code during development.

Toggling verbose mode via API:


// toggle verbose mode via API 
callpage('api.toggleVerbose', true);

Toggling verbose mode via query param:


https://app.callpage.io?__cpVerbose=true

Verbose mode:

CallPage API has verbose mode which could be toggled:

  1. via API
  2. via query param __cpVerbose=true

Alternative debug methods:

  1. Debugging with breakpoints
  2. Exceptions
  3. Pretty Print
  4. Code Pen and JSfiddle – HTML, CSS, and JavaScript code editors in your browser with instant previews.

Support

If you have a problem with an API call, such as it not returning the correct value or not performing the intended action, email support@callpage.io with a link to a page where we can test the functionality and information about the steps that you’ve taken to debug so far.

Widget API

Widget API allows you to interact with widget window, button and others interactive parts.

Anchor

You could manipulate with widget using anchor #cp-widget.

Opens widget on site entering

The simplest way - redirect visitor to URL with anchor #cp-widget

E.g. https://callpage.io/en#cp-widget

<a href="#cp-widget">Click to open CallPage window</a>

Try it

Open widget (api.widget.open)

api.widget.open

callpage('api.widget.open');

Opens CallPage popup window

Close widget (api.widget.close)

api.widget.close

callpage('api.widget.close');

Closes CallPage popup window

Toggle scoring system (api.scoring.toggle)

api.scoring.toggle

callpage('api.scoring.toggle', toggle);

Toggles scoring system on/off. Scoring system - a system of classifying lead according to quality using rules. When any of rules is triggered the score value is changed. When value reached the defined one, CallPage marks user as engaged and triggers popup with custom title displayed.

Parameter Type Required Description
toggle boolean no Toggles on/off scoring system

Set department (api.setDepartment)

api.setDepartment

callpage('api.setDepartment', departmentId);

You can divide CallPage managers into different departments, such as “Billing” or “Support”. For example, if this parameter will point to group “Billing”, all visitors entering ordering the call will talk with managers from this group and not the “Support” group.

Parameter Type Required Description
params object yes
  • tel - Phone number to call in E164 format, e.g. +4888888888
  • department_id - Department unique ID e.g. 123
callback function no Callback will be executed when call is in progress

department_id could also be set with api.setDepartment

Example:

callpage('api.setDepartment', 123);

Perform a call (api.widget.call)

api.widget.call

callpage('api.widget.call', params, callback);

Perform a real-time call through CallPage API.

Parameter Type Required Description
params object yes
  • tel - Phone number to call in E164 format, e.g. +4888888888
  • department_id - Department unique ID e.g. 123
callback function no Callback will be executed when call is in progress

department_id could also be set with api.setDepartment

Example:

// event when the call is ordered. Use callback to get callRequestId
callpage('api.widget.call', {tel: '+48570123123'}, function(response) {

    var callRequestId = response? response.id : null;

    // it means that we successfully ordered a call and have its ID
    if (callRequestId) {
        console.log("Unique call ID: " + callRequestId);
    }
    else {
        // put here any logic if call was unsuccessful (e.g. no managers available, or after hours)
    }
});

Perform a call or order on the first available slot (api.widget.call-or-schedule)

api.widget.call-or-schedule

callpage('api.widget.call-or-schedule', params, callback);

Perform a real-time call through CallPage API or if there are no available managers right now, schedule a call on the first available timeslot.

Parameter Type Required Description
params object yes
  • tel - Phone number to call in E164 format, e.g. +4888888888
  • department_id - Department unique ID e.g. 123
callback function no Callback will be executed when call is in progress

department_id could also be set with api.setDepartment

Example:

// event when the call is ordered. Use callback to get callRequestId
callpage('api.widget.call-or-schedule', {tel: '+48570123123'}, function(response) {

    var callRequestId = response? response.id : null;

    // it means that we successfully ordered a call and have its ID
    if (callRequestId) {
        console.log("Unique call ID: " + callRequestId);
    }
    else {
        // put here any logic if call was unsuccessful
    }
});

Auto-show button (api.button.autoshow)

api.button.autoshow

callpage('api.button.autoshow');

Shows CallPage button after timeout defined in dashboard widget.button.showTimeout. By default this method call is embedded into widget code

Show button (api.button.show)

api.button.show

callpage('api.button.show');

Shows CallPage button with animation immediately

Hide button (api.button.hide)

api.button.hide

callpage('api.button.hide');

Hides CallPage button with animation

Show hint (api.hint.show)

api.hint.show

callpage('api.hint.show');

Shows CallPage hint

Hide hint (api.hint.hide)

api.hint.hide

callpage('api.hint.hide');

Hides CallPage hint

Show eyecatcher (api.eyecatcher.show)

api.eyecatcher.show

callpage('api.eyecatcher.show');

Shows eye catcher

Hide eyecatcher (api.eyecatcher.hide)

api.eyecatcher.hide

callpage('api.eyecatcher.hide');

Hides eye catcher

Start countdown timer (api.countdown.start)

api.countdown.start

callpage('api.countdown.start', selector, onStart, onEnd);

Starts countdown timer on custom element. Allows you to embed countdown timer in your form. This function requires custom markup for valid time updating. Element selector should contain 2 child elements with selectors .cp-countdown__seconds and cp-countdown__miliseconds.

Parameter Type Required Description
selector string yes Valid jQuery selector string
onStart function no Callback will be executed when countdown starts
onEnd function no Callback will be executed when countdown ends

Example:

<div id="countdown">
    <span class="cp-countdown__seconds">29</span>
    <span class="cp-countdown__miliseconds">99</span>
</div>
callpage(
    'api.countdown.start',
    // element selector
    '#countdown',
    // on start callback
    function() {
        // code when countdown starts
    },
    // on end callback
    function() {
        // code when countdown ends
    }
);

Callbacks

Callbacks let you bind a custom JavaScript function to an event. For example, your function can be invoked every time the widget is opened. It’s a great way to extend custom functionality and deeply integrate your site with CallPage.

onReady

event.onReady

callpage('event.onReady', function() {
    // your code here
});

Code included inside event.onReady will only run once the widget is loaded and all resources available.

onWidgetLoaded

event.onWidgetLoaded

callpage('event.onWidgetLoaded', function() {
    // your code here
});

Event onWidgetLoaded fires when widget is loaded properly and available.

onWidgetExit

event.onWidgetExit

callpage('event.onWidgetExit', function() {
    // your code here
});

Event onWidgetExit fires when widget is disabled and can not be loaded.

onWidgetOpened

event.onWidgetOpened

callpage('event.onWidgetOpened', function() {
    // your code here
});

Event onWidgetOpened fires when popup window is opened.

onWidgetClosed

event.onWidgetClosed

callpage('event.onWidgetClosed', function() {
    // your code here
});

Event onWidgetClose fires when popup window is closed.

onButtonShowed

event.onButtonShowed

callpage('event.onButtonShowed', function() {
    // your code here
});

Event onButtonShowed fires when CallPage button is shown.

onCallCreated

event.onCallCreated

callpage('event.onCallCreated', function(call) {
    // get call ID
    var callId = call.id;

    if (call.scheduled_at) {
        // it means that call is "scheduled", created using option "Call me later"
    }

    // your code here
});

Event onCallCreated fires when visitor ordered a call (scheduled or real-time)

onCallRealTime

event.onCallRealTime

callpage('event.onCallRealTime', function(call) {
    // get call ID
    var callId = call.id;

    // your code here
});

Event onCallRealTime fires when visitor ordered a real-time call

onCallScheduled

event.onCallScheduled

callpage('event.onCallCreated', function(call) {
    // get call ID
    var callId = call.id;

    // scheduled timestamp
    if (call.scheduled_at) {
    }

    // your code here
});

Event onCallScheduled fires when visitor ordered a scheduled call

onCallInProgress

event.onCallInProgress

callpage('event.onCallInProgress', function(call) {
    // get call ID
    var callId = call.id;

    // your code here
});

Event onCallInProgress fires when call status changes to IN-PROGRESS. It means that visitor picked up the phone.

onCallCompleted

event.onCallCompleted

callpage('event.onCallCompleted', function(call) {
    // get call ID
    var callId = call.id;

    // your code here
});

Event onCallCompleted fires when call status changes to COMPLETED. It means that the call was successfully finished.

Statistics API

Statistics API allows you to grab some useful information about visitor, widget, status, etc.

getCallId

stats.getCallId

callpage('event.onReady', function() {
    // get callId
    var callId = callpage('stats.getCallId');
    console.log(callId);
});

Returns the unique identificator for the current attempt.

The callId is remembered even when the call ends until the page is refreshed. Returns null if callId is unknown (e.g. call has not yet started).

getManagers

stats.getManagers

callpage('event.onReady', function() {
    // get managers
    var managers = callpage('stats.getManagers');
    console.log(managers);
});

Example output:

[
    {
        "id":28,
        "name":"Admin",
        "avatar":"url-to-avatar",
        "departments":[
            {
                "id": 1,
                "name": "Owner"
            }
        ]
    },
    {
        "id":29,
        "name":"Manager",
        "avatar":"url-to-avatar",
        "departments":[
            {
                "id": 1,
                "name": "Sales"
            }
        ]
    }
]

Returns array of managers which belongs to this widget.

getVisitorId

stats.getVisitorId

callpage('event.onReady', function() {
    // get unique visitor ID
    var visitorId = callpage('stats.getVisitorId');
    console.log(visitorId);
});

Returns the unique identificator of the current visitor.

hasAvailableManagers

stats.hasAvailableManagers

callpage('event.onReady', function() {
    var hasAvailableManagers = callpage('stats.hasAvailableManagers');
    // your code here
});

Returns true if there is at least one available manager who is able to pick up the phone right now.

Tracking code

Tracking code

<!-- BEGIN callpage.io widget -->
<script type="text/javascript">
    var __cp = {
        // your encrypted widget ID, could be find in dashboard
        id: "YOUR-ENCRYPTED-WIDGET-ID",
        version: '1.1'
    };

    // async loader
    (function(window, document) {
        var loader = function() {
            var cp = document.createElement('script'); cp.type = 'text/javascript'; cp.async = true;
            cp.src = "//api.callpage.io+themes+widget+build+js+callpage=js".replace(/[+]/g,'/').replace(/[=]/g,'.');
            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(cp, s);
        };

        window.addEventListener ? window.addEventListener("load", loader, false) : window.attachEvent("onload", loader);

        // prevent from 2 code instances on site
        if (window.callpage) {
            alert('You could have only 1 CallPage code on your website!');
        } else {

            // queue of API calls
            window.callpage = function(method) {
                if (method == '__getQueue') {
                    return this.methods;
                }
                else if (method) {
                    if (typeof window.callpage.execute === 'function') {
                        window.callpage.execute.apply(this, arguments);
                    }
                    else {
                        (this.methods = this.methods || []).push({
                            arguments: arguments
                        });
                    }
                }
            };

            // autoshow button
            callpage('api.button.autoshow');
        }
    })(window, document);
</script>
<!-- END callpage.io widget -->

Insert tracking code right before </body> closing tag

CallPage tracking code is available in the CallPage app.

You can customize the tracking code to send additional information about your visitors to CallPages applications.

CallPage code snippets

We will share with you some useful CallPage snippets and use cases. Feel free to customize them and use :)

CallPage embed into form with countdown timer

Check JSFiddle

Custom CSS

Customize your popup window with CSS

You can spice up your chat window using custom CSS styles and pre-defined SCSS mixins which will simplify your life. Here are some examples of possible customizations and instructions on how to achieve them.

Learn SASS / SCSS

Learn SCSS

How it works

Responsive / mobile websites

Mobile-only

@include breakpoint(mobile) {
    // these rules will be applied only for mobile devices

    #cp-widget .cp-type--minimal .cp-state--call .cp-parts-left__title {
        // example rule
    }
}

Tablet-only

@include breakpoint(tablet) {
    // these rules will be applied only for tablet devices

    #cp-widget .cp-type--minimal .cp-state--call .cp-parts-left__title {
        // example rule
    }
}

Desktop-only

@include breakpoint(desktop) {
    // these rules will be applied only for desktop devices

    #cp-widget .cp-type--minimal .cp-state--call .cp-parts-left__title {
        // example rule
    }
}

CallPage allows you easily define rules only for certain devices

Image background

@mixin bg-image($url, $blur: 0)

// set image as a background with overlay 10%
@include bg-image('//s3-eu-west-1.amazonaws.com/callpage-app/users/widgets/4239/background.jpg', 10);

Sets image as a widget’s background. Background is set on all states with option background-size: cover'. Parameter $blur allows you to put dark overlay on the background.

Mixin bg-image takes 2 parameters:

Parameter Type Required Description
$url string yes Absolute background URL
$blur int no Value from 0 to 100 (%)

Example look

Custom color background

@mixin bg-color($color)

// set custom background color
@include bg-color(red);

Sets custom background color.

Parameter Type Required Description
$color color yes Color in CSS format. E.g. red, #ccc, #fafafa, rgb(30,30,30)

Custom text color

@mixin texts-color($color)

// set custom texts color
@include texts-color(red);

@mixin texts-light

// set light texts color
@include texts-light;

@mixin texts-dark

// set light texts color
@include texts-dark;

Sets custom texts color (titles, paragraphs, etc.)

Parameter Type Required Description
$color color yes Color in CSS format. E.g. red, #ccc, #fafafa, rgb(30,30,30)

Your logotype on widget

@mixin custom-logo($url, $width: 150px, $height: 30px)

// set CallPage logo on the top of the widget with 120px width and 35px height
@include custom-logo('//app.callpage.io/themes/default/build/user/images/logo/logo.png', 120px, 35px);

If you’d like to provide a truly brand-less experience, you can set your logotype on the top of the widget.

Parameter Type Required Description
$url string yes Absolute logotype URL
$width string no Logotype width, default - 150px
$height string no Logotype height, default - 30px

Example look

Change widget’s button position

@mixin cp-button-position($top: ‘inherit’, $right: 'inherit’, $bottom: 'inherit’, $left: 'inherit’)

// Change bottom and left position to 20px 20px
@include cp-button-position('inherit', 'inherit', 20px, 20px);

Change widget’s fixed position. Provide values for each of coordinates. If you want to inherit original position for specific dimension use inherit value.

Parameter Type Required Default Description
$top string no inherit Top position
$right string no inherit Right position
$bottom string no inherit Bottom position
$left string no inherit Left position