Intracom integration

Print Friendly, PDF & Email

Content

Introduction

The library intracom is a top level interface to manage conversation and user presence, and integrate it on a page. It includes Combox library.

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

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

This document describes how to integrate intracom library.

The loader

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

Basic integration

First of all, you need to include the loader in your page :

<script type="text/javascript" src="//cloud.apizee.com/intracom/loaderIntracom.js"></script>

Then call the loader with the configuration :

var apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
};
loadIntracom(apiCCkey, userInfos);

This basic configuration ensures that other Intracom users will see your nickname and presence.

Prototype

The loader prototype:

loadIntracom(apiCCkey,
userInfos,
intracomAppCallback,
null,
intracomParams);

apiCCkey : the apiRTC key defined for your enterprise account
userInfos : javascript structure containing user informations
intracomAppCallback : [optional] a callable function use as callback for binding event
intracomParams: [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 apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
intracomAppCallback = false,
intracomParams = {
culture: 'en'
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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/",
    ...
    intracomParams = {
        culture: 'en',
        labels: {
            newMessagePlaceholder: "Type your message here",
        }
    };
loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

…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 offers the possibility to manage a dynamic button element directly integrated in the page.

Basic Integration

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

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

Replace “XX” with the id of the user (visible in the database) and indicate the name of this user in the “title” field.

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

The default class is used to display the presence, chat or call buttons within the block: intracom-button

The complete list of class and usage:

at.png<br” />

 

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 group 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 ways by defining CSS classes. For example:

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

… will result in : intracom-example-config

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 :

</pre>
<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>
<pre>

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.

 

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 :

</pre>
<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>
<pre>

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 position of the presence bubble, Intracom provides 4 basic classes: 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 uses 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 stylesheet 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 apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
intracomAppCallback = false,
intracomParams = {
comboxDesignURL: '//cloud.apizee.com/comBox/v2.3/combox-design-2.3.css'
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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.

Intracom Event Callback

The third parameter intracomAppCallback (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 apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
intracomAppCallback = function intracomAppCallback(intracom, type, params) {
switch (type) {
case "init":

break;
case "updatePresence":

break;
...
}
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback);

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

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

var apiCCkey = "API key from Apizee",
...
intracomAppCallback = function intracomAppCallback(intracom, type, params) {
switch (type) {
case "init":
alert('Intracom is loaded');
break;
}
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback);

Event list

Complete list of events:

Event type

Description

Params

init Intracom 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. Query 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
 }

 

Intracom API

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

Intracom accessor :

var instanceIntracom = Apizee.getIntracom();

Intracom.openChat

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

/**
* @param {Integer} destId Destination user ID to fetch
*/
instanceIntracom.openChat(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 loadIntracom() as described below:

var apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
intracomAppCallback = false,
intracomParams = {
directory: true
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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

Annuaire widget

Additionnal options

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

var apiCCkey = “API key from Apizee”, … intracomParams = { directory: true, directoryStartOpen: false }; loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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

 var apiCCkey = "API key from Apizee",
...
intracomParams = {
directory: true,
directoryStartOpen: false,
directoryFixed: true,
directoryFixedPosition: 'right' // by default
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);
                Annuaire réduit                                                      Annuaire fixe ouvert
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/",
...
intracomParams = {
directory: true,
inviteDestUrl: "//your-domain.tld/invite-page"
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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

var apiCCkey = "API key from Apizee",
userInfos = {
nickname: "",
firstName: "",
lastName: "",
mail: "",
photoUrl: ""
};

loadIntracom(apiCCkey, userInfos);

Embed directory

The directory can be used independently of box system, in order to embed it on the page body.
Intracom 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 apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg",
},
useFrame = true,
intracomAppCallback = function(intracom, type, params) {
switch (type) {
case "init":
var el = $jqApz('#embedDirectory');
el.show();
Apizee.getIntracomDirectoryManager().addPanel('panelId', el);
break;
}
},
intracomParams = {
directory: true, // enable directory system
directoryWidget: false, // to disable managed directory in box system
directoryBoxEmbed: false // to disable embed directory in box system
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, useFrame, intracomParams);
</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');

Others options

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

 var serverDomainRoot = "//cloud.apizee.com/",
apiCCkey = "API key from Apizee",
userInfos = {
id: xx,
nickname: "John",
firstName: "John",
lastName: "Doe",
mail: "john.doe@mail.com",
photoUrl: "//your-domain.tld/user-photo.jpg"
},
intracomAppCallback = false,
intracomParams = {
onlyChat: true
};

loadIntracom(apiCCkey, userInfos, intracomAppCallback, null, intracomParams);

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