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.

Make sure you have the latest CallPage embed code.
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.

Debug methods:

Debugging with breakpoints
Exceptions
Pretty Print
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 allows you to interact with widget window, button and others interactive parts.

Anchor

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

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

api.widget.open

callpage('api.widget.open');

Opens CallPage popup window

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 variable of custom rule (api.scoring.setVariable)

api.scoring.setVariable

callpage('api.scoring.setVariable', 6);


callpage('api.scoring.setVariable', 'hello');

Scoring system provides special custom rule. When you create one in the dashboard you specify its value and comparison condition. JavaScript API api.scoring.setVariable accepts variable which gets compared with the value of custom rule. If the condition matches custom rule triggers.

Parameter	Type	Required	Description
variable	number \| string	yes	The variables which gets compared with the value of custom rule.

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);

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)
    }
});

api.widget.schedule

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

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.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) {
    // call variable contains call ID 
    // 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

CallPage embed into form with countdown timer

Check JSFiddle

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

CallPage Custom CSS now supports SASS (SCSS) syntax. It means that you could use all features from SCSS: variables, mixins, etc.

Learn SASS / SCSS

Learn SCSS

How it works

Use Inspect element to find selector which should be styled. It's very important to use correct selector.
All rules will be set to !important after compilation
All rules will be automatically minified after compilation
All rules will be prepended with selector #cp-widget after compilation to prevent overriding website styles

Responsive / mobile websites

Mobiles and small tablets.

@include media-breakpoint-down(tablet) {
    // these rules will be applied for mobiles and small tablets.

    #callpage .cp-call__heading {
        // your styles
    }
}

Tablets and desktops.

@include media-breakpoint-up(tablet) {
    // these rules will be applied for tablets and desktops.

    #callpage .cp-call__heading {
        // your styles
    }
}

CallPage allows you easily define rules only for certain devices. Currently there is only tablet breakpoint.

Theming

@mixin main-color(
  $color,
  $divider-amount: 6%,
  $background-active-amount: 6%,
  $background-secondary-amount: 10%,
  $background-tooltip-amount: 8%
)

// Set lightblue as widget theme.
@include main-color(lightblue);


// Sets 'lightblue' as background color of the elements and 
// make the color of agreement tooltip 12% DARKER than given 'ligthblue' color.
@include main-color(lightblue, $background-active-amount: 12%);


// Set 'lightblue' color as widget theme.
@include main-color(lightblue);
// If you want to replace auto-generated color of selected tab
// with your own color.
@include background-active-color(tomato);

There are two widget themes which you can choose in the dashboard: light and dark ones. But if they are not enough for you, use main-color mixin which creates theme based on given $color. This mixin tries "intelligently" detect colors for:

Background of widget, button tooltip, agreement tooltip, contact type tabs and etc.
Borders, lines and dividers
Fonts. Text color will be light if user-defined themed color is dark and vise versa.

You can easily control "intelligent" behavior by using optional arguments described below.

Parameter	Type	Default	Description
$color	color	-	Color in CSS format. E.g. red, #ccc, #fafafa, rgb(30,30,30)
$divider-amount	number	6%	The amount to adjust `$color` variable by, to get a color of dividers, e.g. border of inputs, lines between contact type tabs, border of button tooltip.
$background-active-amount	number	6%	The amount to adjust `$color` variable by, to get background color of active elements, e.g. selected contact type.
$background-secondary-amount	number	10%	The amount to adjust `$color` variable by, to get color of secondary background, e.g. in countdown timer, star rating
$background-tooltip-amount	number	8%	The amount to adjust `$color` variable by, to get color of tooltip, e.g. agreement tooltip

main-color uses under the hood other mixins: background-color, text-color, divider-color.

Background color

@mixin background-color(
  $color,
  $active-amount: 6%,
  $secondary-amount: 10%,
  $tooltip-amount: 8%
)

// Sets 'lightblue' as background color of the elements.
@include background-color(ligthblue);

// Sets 'lightblue' as background color of the elements and 
// make the color of agreement tooltip 10% DARKER than given 'ligthblue' color.
@include background-color(ligthblue, $tooltip-amount: 10%);

// Sets 'black' as background color of the elements and 
// make the color of agreement tooltip 10% LIGHTER than given 'black' color.
@include background-color(black, $tooltip-amount: 10%);

Sets custom background color of the elements: widget, selected contact type tab, button tooltip, agreement tooltip and so on.

Sometimes we want to highlight certain state of element. For example when contact type tab is selected. That's why we need diffrent variations of background color. Fortunately you don't have to worry about all those colors because background-color mixin does it under the hood. All you need to do is just specify $color variable. There are also optional arguments which allow you to configure generating of colors.

Depending on which color user provides mixin will generate lighter or darker colors. Let's say you provide dark color, then the color of the selected tab will be light. And vice versa.

Parameter	Type	Default	Description
$color	color	-	Color in CSS format. E.g. red, #ccc, #fafafa, rgb(30,30,30)
$active-amount	number	6%	The amount to adjust `$color` variable by, to get background color of active elements, e.g. selected contact type.
$secondary-amount	number	10%	The amount to adjust `$color` variable by, to get color of secondary background, e.g. in countdown timer, star rating
$tooltip-amount	number	8%	The amount to adjust `$color` variable by, to get color of tooltip, e.g. agreement tooltip

background-color uses under the hood other mixins: background-active-color, background-secondary-color.

First try to set background color with main-color mixin. If the one doesn't give you desired result then use background-color mixin instead.

If you set background color it makes sense to use text-color and divider-color mixins as well.

Background color of active elements

@mixin background-color($color)

@include background-active-color(ligthblue);

Sets background color for active elements: selected contact type.

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

Use background-color mixin if you want to change the background color of all elements.

Secondary background color

@mixin background-secondary-color($color)

// Sets 'lightblue' as background color of the certain elements.
@include background-secondary-color(ligthblue);

Sets background color for elements such as: circle of countdown timer and inactive start in star rating.

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

Use background-color mixin if you want to change the background color of all elements.

Divider color

@mixin divider-color($color)

@include divider-color(tomato);

Sets color for elements such as: tabs dividers, input border, border of button tooltip, link underline ans so on.

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

This mixin uses under the hood button-tooltip-border-color.

@mixin button-tooltip-border-color($color)

@include button-tooltip-border-color(tomato);

Sets the border color of button tooltip. Tooltip is the component which appears over widget button. It's used for one click to call feature and showing info about active call if the widget is closed.

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

Text color

@mixin text-color($color)

@include text-color(black);

Sets color for titles, paragraphs, close icon etc.

Callpage widget uses different colors for main text and secondary text. Fortunatelly, you don't have to worry about colors variations. You need only pass the $color of the main text and text-color mixin will create other colors for you. The color of the secondary text is generated in the way the one to be less noticeable than the main text.

If the generated color of secondary text doesn't match your needs, you can directly call small-secondary-text mixin to set desired color.

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

This mixin uses under the hood small-secondary-text-color.

Small text color

@mixin small-secondary-text-color($color)

@include small-secondary-text-color(black);

Sets color for elements such as agreement short text or count of social shares.

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

Use text-color mixin if you want to change the color for all texts.

Brand button customization

@mixin text-color { ...your styles }

@include brand-button {
  letter-spacing: 1px;
  font-size: 16px;
}

Applies styles for the brand button.

Javascript API

Our documentation to help you customize CallPage to fit your website

Testing and Debugging

Debug methods:

Support

Widget API

Anchor

Opens widget on site entering

Opens widget on link clicking

Open widget (api.widget.open)

Close widget (api.widget.close)

Toggle scoring system (api.scoring.toggle)

Set variable of custom rule (api.scoring.setVariable)

Set department (api.setDepartment)

Perform a call (api.widget.call)

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

Auto-show button (api.button.autoshow)

Show button (api.button.show)

Hide button (api.button.hide)

Show hint (api.hint.show)

Hide hint (api.hint.hide)

Show eyecatcher (api.eyecatcher.show)

Hide eyecatcher (api.eyecatcher.hide)

Start countdown timer (api.countdown.start)

Callbacks

onReady

onWidgetLoaded

onWidgetExit

onWidgetOpened

onWidgetClosed

onButtonShowed

onCallCreated

onCallRealTime

onCallScheduled

onCallInProgress

onCallCompleted

Statistics API

getCallId

getManagers

getVisitorId

hasAvailableManagers

Tracking code

Insert tracking code right before </body> closing tag

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

Custom CSS

Customize your popup window with CSS

Learn SASS / SCSS

How it works

Responsive / mobile websites

Theming

Background color

Background color of active elements

Secondary background color

Divider color

Border color of button tooltip

Text color

Small text color

Brand button customization

Insert tracking code right before `</body>` closing tag