1. Home
  2. Docs
  3. Developer
  4. Combox integration

Combox integration

Print Friendly, PDF & Email

Content

Introduction

The library Combox maintain the connection to Apizee plateform (with ApiRTC library) and provide the graphical component used to display ongoing conversations.

This document describes how to integrate combox library.

The loader

This loader is the entry point for custom configuration, like translation, user information, event binding…

Basic integration

First you need to include the loader in your page :

<script type="text/javascript" src="//cloud.apizee.com/comBox/loaderComBox.js"></script>

Then call the loader with the configuration :

 var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
photoUrl: "//your-domain.tld/user-photo.jpg"
};
loadComBox(serverDomainRoot , apiCCkey, userInfos);

This basic configuration ensures that others users will see your nickname and presence on apiRTC.

Prototype

The loader prototype :

loadComBox(serverDomainRoot,
apiCCkey,
userInfos,
comboxAppCallback,
comboxParams);

serverDomainRoot : url of the Apizee platform, if you don’t have a personal server, use “//cloud.apizee.com/”
apiCCkey : the apiRTC key defined for your enterprise account
userInfos : javascript structure containing user informations
comboxAppCallback : [optional] a callable function use as callback for binding event
comboxParams : [optional] a structure containing extra parameters

Language selection

Several language packs are available to translate the dialog box, you can use it by setting the parameter “culture” in the loader params structure, like this :

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
comboxAppCallback = false,
comboxParams = {
culture: 'en'
};

loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback, null, comboxParams);

Possible values : fr / en / es / de / nl

You can also define part or the full list of labels directly in the params object, like this:

var serverDomainRoot = "//cloud.apizee.com/",
...
comboxParams = {
culture: 'en',
labels: {
newMessagePlaceholder: "Type your message here",
}
};
loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback, comboxParams);

…where newMessagePlaceholder is the unique label identifier, and “Type your message here”, the corresponding translation.

The complete labels list is available at //cloud.apizee.com/comBox/lang.php?v=X.x&lg=YY, where parameter v stands for the dialog box version (or “last” to get the last one), and lg for the language, for example:
//cloud.apizee.nico/comBox/lang.php?v=last&lg=en
… will get all english labels for the last version.

Design customization

The box can redesign by changing the CSS stylesheet, this can be done with the additionnal parameter comboxDesignURL:

 apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
comboxAppCallback = false,
comboxParams = {
comboxDesignURL: '//cloud.apizee.com/comBox/v3.9/combox-design-3.9.css'
};

loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback, comboxParams);

ComBox is provided with a base template design in combox-design stylesheet. You can find source at //cloud.apizee.com/comBox/v3.9/combox-design-3.9.css

Take into consideration that combox include a reset CSS for root container #comBoxAll to avoid interference with existing website. You must use more powerful CSS selector to apply style on this structure.

Combox Event Callback

The third parameter comboxAppCallback (see the loader prototype section) can be used to execute some code on events fired by comBox.

Integration

To use this callback, you must define a callable function on the loader:

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
comboxAppCallback = function comboxAppCallback(combox, type, params) {
switch (type) {
case "init":

break;
case "updatePresence":

break;
...
}
};

loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback);

comboxAppCallback is called with 3 parameters, the combox instance first, then the event type, and the events params in third.

For example if you want an alert to be displayed when the combox is loading:

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
...
comboxAppCallback = function comboxAppCallback(combox, type, params) {
switch (type) {
case "init":
alert('Combox is loaded');
break;
}
};

loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback);

Event list

Complete list of events:

Event type

Description

Params

init Combox is loaded and ready to work.
createNewIMDiv Fired when a new box container has been created.
{
     destId:Integer, // destination user id
     nickname:String // destination user nickname
 }
openComBox Fired when a box is opened. jQuery object of the box container
minimize Fired when a box is minimized. destId:Integer // destination user id
maximize Fired when a box is maximized. destId:Integer // destination user id
close Fired when a box is closed. destId:Integer // destination user id
putInFrame Fired when the page has been reloaded into navIframe.
showNewMessage Fire when a new message is shown.
 {
     nickname:String, // sender nickname
     destId:Integer, // destination user id
     message:String, // new text message
     html:String, // new html message
 }
sendMessage Fired when a message is sent
 {
     destId:Integer, // destination user id
     message:String // sent message
 }
updatePresence Fired when the presence information of other users changes : online / offline
 detail:{
     eventType:String, // string representing the event type
     time:String, // Date of the event
     connectedUsersList:Array, // List of connected users
     state:String, // status of the users : online or offline
 }
callRecept Fired when a call audio or video is incoming
{
      callerId:Integer, // user calling id
      callerNickname:String, // caller nickname
      callId:Integer // Call id
 }
callTransmit Fired when a call audio or video is transmit
{
      destId:Integer, // destination user id
      nickname:String, // destination user nickname
      callId:Integer // Call id
 }
callEnd Fired when a call audio or video is hangup
{
      from: Integer, //user id who stop the call
      callId:Integer, //call id stopped
      msg: String //message which explain why the call stopped
 }
callBreak Fired when a call audio or video is interrupted
{
      from: Integer, //user id who stop the call
      callId:Integer, //call id stopped
      msg: String //message which explain why the call stopped
 }
callEstablished Fired when a call Audio/ Video is established (medias are loaded)
{
      callType: String, // the call type
      destId:Integer, //correspondant id
      time:String // Date of the event
 }

Combox API

Combox expose some functionnality to manage user session & data.

Retrieve library instance

Apizee library describe an accessor on a global structure, and offer a simple way to retrieve instance of combox through the current page or child iframe.

Combox accessor :

var instanceCombox = Apizee.getComBox();

Combox.openBox

To open a chat box with a specific user nickname, use :

/**
* @param {Integer} destId Destination user ID to fetch
* @param {Array} boxParams {title, minTitle, nickname, classToAdd, offlineMessage}
*/
instanceCombox.openBox(destId, boxParams);

Combox.close

To close a chat box with a specific destId, use :

/**
* @param {Integer} destId Destination user ID to fetch
* @param {callable} callback A callable function called after closed
*/
instanceCombox.close(destId, callback);

Combox.getCapabilities(destId)

To get usable capabilities (call, chat, whiteboard, …) with a specific destId, use :

/**
* @param {Integer} destId Destination user ID to fetch
* @return {json} Object containing combined local + remote destID capabilities
*/
instanceCombox.getCapabilities(destId);

It will return object like that :

Object {canCallVideo: 1, canCallAudio: 1, canChat: 1, canWhiteboard: 1, canScreenShare: 1}

/!\ Note that this method does not take into account the current state of getUserMedia request: for example on chrome it can be saved as refused by default after one rejected request.


Other options

This array describe the other extra parameters that can be used in comboxParams:

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
comboxAppCallback = false,
comboxParams = {
onlyChat: true
};

loadComBox(serverDomainRoot, apiCCkey, userInfos, comboxAppCallback, comboxParams);

 

Option name

Description

Possible values

onlyChat Force disable of call features. true / false (default)
audioOnly Disable video call. true / false (default)
confCall Enable conference call feature. true (default) / false
callButton Show / hide call button. true (default) / false
closeButton Show / hide close button on box. true (default) / false
autoAcceptCall Enable auto accept on incoming call. true / false (default)
autoSwitchFullscreenOnAcceptCall Automaticaly switch on fullscreen when accepting call.
Can’t be use with autoAcceptCall:true.
true / false (default)
callHistory Enable the call history. true / false (default)
confPanel Enable the config panel to manage user option when available. true (default) / false
enableSystemTrayNotification Enable the desktop notification features when available.
Note that this features must be manually granted by user.
true (default) / false
disableDnD Disable the drag and drop features on box containers. true / false (default)
forceMediaGranted Force media access as granted. It can be useful on preconfigure settings. true / false (default)
singleInstance Force to use only one box on the page. If multiple chat incoming at the same time, the unique box will be replace. true / false (default)
comBoxBodyContainer If set, the div id will be used as global container for new box.
Note that some features can be disable using this option.
div #id
outgoingCallTone Sound notification for outgoing call tone.
 [
     ['audio/mpeg', "//cloud.apizee.com/comBox/sound/wait-tone.mp3"],
     ['audio/wav', "//cloud.apizee.com/comBox/sound/wait-tone.wav"]
 ]

or custom URL for both mp3 and wav format
or false to disable

incomingCallTone Sound notification for incoming call tone.
 [
     ['audio/mpeg', "//cloud.apizee.com/comBox/sound/call-tone.mp3"],
     ['audio/wav', "//cloud.apizee.com/comBox/sound/call-tone.wav"]
 ]

or custom URL for both mp3 and wav format
or false to disable

newMessageTone Sound notification for new incoming message.
 [
     ['audio/mpeg', "//cloud.apizee.com/comBox/sound/new-message.mp3"],
     ['audio/wav', "//cloud.apizee.com/comBox/sound/new-message.wav"]
 ]

or custom URL for both mp3 and wav format
or false to disable

messageTone Sound notification for each message.
 [
     ['audio/mpeg', "//cloud.apizee.com/comBox/sound/message.mp3"],
     ['audio/wav', "//cloud.apizee.com/comBox/sound/message.wav"]
 ]

or custom URL for both mp3 and wav format
or false to disable

presenceTone Sound notification for update presence.
 [
     ['audio/mpeg', "//cloud.apizee.com/comBox/sound/presence.mp3"],
     ['audio/wav', "//cloud.apizee.com/comBox/sound/presence.wav"]
 ]

or custom URL for both mp3 and wav format
or false to disable

template The theme name default (default) / blue
templateUrl Custom your template with your own stylesheet url null (default) /

TEMPLATE_URL.css

useFrame A boolean to enable or disable use of iframe when calling true / false (default)
minimizeTitle A string which is the box title “”(default agent nickname) / String
mediaGranted Grant access to media true / false (default)
comAppDivId If set, the div id will be used as the app div for the box. div#id
culture Set the box language en (default) / fr / de / es / nl
whiteboard Enable whiteboard functionality to draw. It auto show your drawing to the agent true / false (default)
whiteboardShowBtn Show whiteboard buttons which allow saving, reset whteboard, take a local snapshot, change painter color and change painter width. true (default) / false
recordActivated Enable agent recording audio or video call true / false (default)
recordAllowRemoteCmd Show recording buttons which allow agent recording audio or video call true / false (default)
cloudSessionId If it set your recordings files will be sent SessionID
typingEventTimeout The time interval (in seconds) during which we have to show that the agent is pressing a key int (2 default)
autoMaximize If set the box will open with a maximize size true / false (default)
maximizedAreaContainer If set, a div will be used as the box in maximized format div#Id
screensharing User can share his screen to his correspondent true / false (default)
screensharingShowBtn This params show the screensharing functionniality buttons true / false (default)
screensharingShowRemoteBtn This params show the screensharing functionniality buttons on the corresponding side true / false (default)
forceProtocol Force the http or https protocol current protocol
displayMediaRequestOverlay Display an overlay popup which explain how activate your devices (webcam, microphone) true (default)/ false
webRTCPluginActivated Enable Web rtc plugin management true / false (default)
Was this article helpful to you? Yes No