Agent integration

Print Friendly, PDF & Email

Content

Introduction

The library agent is a top level manager for IzeeChat conversation on administration side. It includes both Intracom & Combox library.

Intracom manages dynamic elements integrated on the page. Its job is to intercept user communication event, like availability or call status, and update element to show real time information.

On the other hand, Combox maintains the connection to Apizee plateform (with ApiRTC library) and provide the graphical component used to display ongoing conversations.

This document describes how to integrate agent 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/agent/loaderAgent.js”></script>

Then call the loader with the configuration :

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
firtsname: "John",
lastname: "Doe",
nickname: "Johnny",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
};
loadAgent(serverDomainRoot, apiCCkey, userInfos);

This basic configuration ensures that your visitors will see John as a connected agent.

You can retrieve your user’s token by using API REST /token. (see //dev.apirtc.com/api/reference_apiRTC_REST for details)

Warning: Token as a limited duration, so you should implement a log-in process on your page to ensure a durable behavior. (/token to log, then /v2/users/me to retrieve userInfos values)

Prototype

The loader prototype :

loadAgent(serverDomainRoot,
apiCCkey,
userInfos,
agentAppCallback,
useFrame,
agentParams);
1. serverDomainRoot : url of the Apizee platform, if you don’t have a personal server, use “//cloud.apizee.com/”
2. apiCCkey : the apiRTC key defined for your enterprise account
3. userInfos : javascript structure containing user informations
4. agentAppCallback : [optional] a callable function use as callback for binding event
5. useFrame : [optional] a boolean to enable or disable use of iframe when calling
6. agentParams : [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,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
firtsname: "John",
lastname: "Doe",
nickname: "Johnny",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
useFrame = true,
agentAppCallback = false,
agentParams = {
culture: 'en'
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

Possible values : fr / en / es / de / nlYou can also define part or the full list of labels directly in the params object, like this:

var serverDomainRoot = "//cloud.apizee.com/",
...
agentParams = {
culture: 'en',
labels: {
newMessagePlaceholder: "Type your message here",
}
};
loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

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

Dynamic call buttons

Intracom offer possibility to manage dynamic button element directly integrated on the page.

Basic Integration

To insert a call button on the page, simply set block or div with CSS class Name intracomUserStatus:

<span class="intracomUserStatus" rel="XX" title="pseudo"></span>

Replace XX with the id in your database of the user for which you want to display the status in the rel field and indicating the name of this user in the title field.

The Intracom complete script block with the HTML needed to display presence information and chat buttons and call.

The default class is used to display the presence, chat or call buttons within the block:Boutons chat visio ajouter un participant

The complete list of class and usage:

Classname usages

Functions performed

Icons

intracomUserStatus By default presence + chat + video call + group (if another box is present)
intracomUserStatus presence Presence only  Presence only
intracomUserStatus chat chat only  Chat only
intracomUserStatus group groupe chat (if another box is present)  Ajouter un participant chat
intracomUserStatus call Video call  Video call
intracomUserStatus audio Audio only call  Audio only intracom

 

The functions can be combined in different way by defining css classes. For example:

<span class="intracomUserStatus presence chat audio" rel="36" title="Paul"></span>

… will result in :

Extended integration

It is possible to integrate a call button with an overlay with a tooltip on an existing block, like an image or in some box.

To do that, simply insert the call button span or div block in the item to cover, add tooltip class, then specify the class corresponding to the parent box in the attribute tooltip-hover:

<div class="avatar"><a href="//mydomain/profil/user/8">
<img src="./images/user/8.jpg" alt="Johnny Who" />
</a>
<span class="intracomUserStatus tooltip" rel="8" title="Johnny Who" tooltip-hover="avatar"></span>
</div>

Intracom completes the block with the needed HTML code to display the user presence information on overlay of the element, the chat and call button when the mouse is over this element.

By default, the presence bubble is displayed at the bottom right of the selected box.

 

Customization
To set the presence bubble position, Intracom provide 4 basic class top, bottom, left and right. For example :

<span class="intracomUserStatus tooltip top left" rel="8" title="Johnny Who" tooltip-hover="avatar"></span>

The tooltip can also be stylized via the attribute tooltip-class. The following example use the white class provided by Intracom :

<span class="intracomUserStatus tooltip top left" rel="8" title="Johnny Who" tooltip-hover="avatar" tooltip-class="white"></span>

Note: The classes provided are given as an example and can be changed in the style sheet of the host site.

Design customization

 

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

 var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
firtsname: "John",
lastname: "Doe",
nickname: "Johnny",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
useFrame = true,
agentAppCallback = false,
agentParams = {
comboxDesignURL: '//cloud.apizee.com/comBox/v2.3/combox-design-2.3.css'
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

ComBox is provided with a base template design in combox-design stylesheet. You can find source at //cloud.apizee.com/comBox/v2.3/combox-design-2.3.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.

Agent Event Callback

 

The fourth parameter agentAppCallback (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,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
firtsname: "John",
lastname: "Doe",
nickname: "Johnny",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
agentAppCallback = function agentAppCallback(agent, type, params) {
switch (type) {
case "init":

break;
case "updatePresence":

break;
...
}
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback);

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

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

var serverDomainRoot = "//cloud.apizee.com/",
...
agentAppCallback = function agentAppCallback(agent, type, params) {
switch (type) {
case "init":
alert('Agent is loaded');
break;
}
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback);

Event list

Complete list of events:

 

Event type

Description

Params

init Agent 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
 }

Agent API

Agent 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 agent through the current page or child iframe.

Agent accessor :

var instanceAgent = Apizee.getAgent();

Agent.comBox.openBox

To open a comBox with a specific user, use :

/**
* @param {Integer} destId Destination user ID to fetch
* @param {Object} boxParams comBox parameters
*/
var instanceCombox = Apizee.getComBox();
instanceCombox.openBox(destId,boxParams);

For more details, check : //doc.apizee.com/docs/developer/combox-integration/#Combox.openBox

Agent.getHistory

To get the user chat history, you can use the getHistory function, whose definition is :

/**
* @param {Integer} destId Destination user ID to fetch
* @param {Integer} nbMessHistory Number of message history
* @param {Function} callback Callable function to call once history is fetch
* @param {Integer} lastMessTimestamp Timestamp of the last message
* @param {Boolean} onlyDestMessage True to get only user message
*/
instanceAgent.getHistory(destId, nbMessHistory, callback, lastMessTimestamp, onlyDestMessage);

Example of use to fetch last 15 messages of the user 42:

instanceAgent.getHistory(42, 15, function(messages) {
messages.forEach(function(message){
console.log(message);
});
});

Agent.getGeoLoc

The HTML geolocation API can be use to retrieve the localisation data from the remote user through agent getGeoLoc function :

/**
* @param {Integer} destId Destination ID to request
* @param {Callable} callback Callback executed on return
*/
instanceAgent.getGeoLoc(destId, function(error, pos) {
// callback to handle pos data when accepted by remote user;
});

The data (including position and exception) returned is the same structure provide by the browser native API. Please refer to the W3C API specification.

/!\ Be careful that the response sent by the browsers depends on their capabilities to retrieve geolocalization information on system. For example, chrome desktop will return the closest ISP public point coordinates. Whereas Firefox desktop will return an empty position.

Example of use with the google reverse geocode api:

instanceAgent.getGeoLog(destId, function(error, pos) {
if (typeof pos.coords !== 'undefined') { // if data present
$.getJSON('//maps.google.com/maps/api/geocode/json?latlng=' + pos.coords.latitude + ',' + pos.coords.longitude + '&amp;sensor=false&amp;callback=?', function(data) {
if (data.status === 'OK') {
console.log(data);
}
});
}
});

Refer to this table for browser compatibility.

Agent.takeRemoteSnapshot

To take a snapshot when remote video is On, you can use the takeRemoteSnapshot function, whose definition is :

/**
* @param {Integer} destId Destination ID to request
*
*/
instanceAgent.takeRemoteSnapshot(destId)

Agent.takeLocalSnapshot

To take a snapshot when local video is On, you can use the takeLocalSnapshot function, whose definition is :

/**
* @param {Integer} destId Destination ID to request
*
*/
instanceAgent.takeLocalSnapshot(destId);

 

User directory widget

Intracom integrates a user directory widget that provides a simple solution to show the list of users and access to all groups, search or invite features without adding specific buttons on your pages.

Activate the widget

To use this widget, you must add the parameter directory and additional user information firstName, lastName and mail on loader loadAgent() as described below

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
nickname: "John Smith",
photoUrl: "//your-domain.tld/user-photo.jpg",
firstName: "John",
lastName: "Smith",
mail: "john.smith@domain.tld"
},
useFrame = true,
agentAppCallback = false,
agentParams = {
directory: true
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

Additional user information is necessary to complete the directory and for search features.
Once activated, all registered users will be displayed in the directory, and available for searching (see the user documentation for more information).

intracom-directory

Additionnal options

The directory is displayed by default. To reduce at startup you can use the parameter directoryStartOpen set to false: intracom-directory-reduce

var serverDomainRoot = "//cloud.apizee.com/",
...
agentParams = {
directory: true,
directoryStartOpen: false
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

To fix the position of the directory on the page, use the parameters directoryFixed (true / false) and directoryFixedPosition (left /
right) :

var serverDomainRoot = "//cloud.apizee.com/",
...
agentParams = {
directory: true,
directoryStartOpen: false,
directoryFixed: true,
directoryFixedPosition: 'right' // by default
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

intracom-directory-fixed-reduced  intracom-directory-fixed-right
reduced on right open on right

Invitation system

This widget also includes an invitation mechanism for registered or external users. It can be used to invite connected users directly to a group chat, or send a request by mail to some or all of the selected users (the mail will be sent to disconnected or external users).

The invitation mail contains a link that allows the users to join a group chat. By default, Intracom uses a generic landing page on the cloud.apizee.com platform where all invited users meet.
This page can be customized by setting an URL on the parameter “inviteDestUrl” in the loader. This page must not be redirected, or the invitation information will be lost.

var serverDomainRoot = "//cloud.apizee.com/",
...
agentParams = {
directory: true,
inviteDestUrl: "//your-domain.tld/invite-page"
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

The custom landing page must include an Intracom loader with an empty configuration to ensure that users arriving connect with request information:

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
nickname: "",
firstName: "",
lastName: "",
mail: "",
photoUrl: ""
};

loadAgent(serverDomainRoot, apiCCkey, userInfos);

Embed directory

The directory can be used independently of box system, in order to embed it on the page body.
Agent provite a directory manager “Apizee.getIntracomDirectoryManager()” to add or remove directory panel on the page :

<section id="embedDirectory"></section>
<script type="text/javascript" src="//cloud.apizee.com/intracom/loaderIntracom.js"></script>
<script type="text/javascript">
var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
nickname: "John Smith",
firstName: "John",
lastName: "Smith",
mail: "john.smith@domain.tld",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
useFrame = true,
agentAppCallback = function(intracom, type, params) {
switch (type) {
case "init":
var el = $jqApz('#embedDirectory');
el.show();
Apizee.getIntracomDirectoryManager().addPanel('panelId', el);
break;
}
},
agentParams = {
directory: true, // enable directory system
directoryWidget: false, // to disable managed directory in box system
directoryBoxEmbed: false // to disable embed directory in box system
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);
</script>

It use the same stylesheet as the full managed directory in box, but it can be easily override by the hosted stylesheet.

For more options, see the full list of directory parameter :

{
showMail: false, // display email of user in the list
initialSearch: "*", // set the initial search info
initialUserState: "connected", // specify the group of user to fetch, can be "connected", "disconnected", or "all"
hideInviteTab: false, // true to hide the invitation tab panel
inviteTabOnly: false, // true to show contact & invite panel
onInviteCancel: function() {}, // throw when an invitation is cancel by user
onInviteSubmit: function() {}, // throw when an invitation is submitted
onInviteChat: function() {}, // throw when a chat invitation is submitted
onInviteVideo: function() {}, // throw when a video invitation is submitted
onUserSelect: function() {}, // throw when a user is selected on invite list
onUserDeselect: function() {}, // throw when a user is deselected on invite list
onUserAdd: function() {}, // throw when a user is added on list : when user connect
onUserRemove: function() {}, // throw when a user is removed from list : when user disconnect
onUserOpen: function() {}, // throw when click on user in first
labels: { // full label list
"connected": "connected",
"notConnected": "not connected",
"discuss": "Discuss",
"searchContact": "search name, email",
"searchNoResult": "no results",
"mailAction": "Invite by mail",
"inviteToDicuss": "Invite to discuss",
"cancelAction": "Cancel",
"searching": "searching...",
"inviteBtn": "Invite",
"sendingInvite": "Sending",
"sendedInvite": "Invitation sended",
"sendingInviteError": "Sending error",
"myConference": "My conference",
"joinMyConference": "Join my conference",
"chatOnlyOnPage": "Chat",
"chatOnlyOnPageTitle": "Send invite to chat on this page",
"videoConferencePage": "Vidéo conférence",
"videoConferencePageTitle": "Send invite and join video conference room page",
"inviteMessagePlaceholder": "Type invite message here",
"invitationTitle": "Invitation form",
"directoryTabContact": "Contacts",
"directoryTabInvite": "Invitation",
"inviteCancelTitle": "Go back to user",
"inviteAdd": "Add",
"inviteAddTitle": "Add people in dicussion"
}
}

Options must be passed on third parameters of addPanel method :

Apizee.getIntracomDirectoryManager().addPanel('id', el, {
hideInviteTab: false,
inviteTabOnly: false,
onUserOpen: function(directory, li) {
console.log(li);
}
});

The panel can be removed with method removePanel(id), ex :

Apizee.getIntracomDirectoryManager().removePanel('id');

Other options

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

var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx",
nickname: "John Smith",
firstName: "John",
lastName: "Smith",
mail: "john.smith@domain.tld",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
useFrame = true,
agentAppCallback = false,
agentParams = {
onlyChat: true
};

loadAgent(serverDomainRoot, apiCCkey, userInfos, agentAppCallback, useFrame, agentParams);

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

Was this article helpful to you? Yes No