Intro

While working on the babblevoice desktop we realised that we had a powerful platform for integration and there were a lot of points where personalised functionality could be useful. We also liked the idea of moving some of the functionality found in our desktop applications to this more user friendly platform with better web integration.

To this end we decided to create the babblevoice desktop plugin framework. If you are interested in creating a plugin please use the api documented below to help along with the examples here. We are very keen to see lots of people using this and hope it can help you. If you would like any further assistance the best place to request help is in our google groups forum and we will do our best to help.

The babblevoice Dekstop uses the presence API directly, you can create your own Javascript to build upon your Web CRM/Application, or you can use this framework to build upon this application.

Known plugins

On the plugin popup of the babblevoice desktop we have a section for known plugins, if you have written a plugin and feel it could be useful for other members of the babblevoice community, feel free to get in touch and we will review and then add your plugin into the known plugins box, feel free to add some light advertising of yourself to the plugin.

Your plugin

Plugins are javascript files which integrate with the babblevoice Desktop using the below API. plugins can be placed anywhere which is accessible from the web, to add a plugin for testing simply follow these instructions.

onInit

Parameters - none Description The First thing you need in a plugin for the babblevoice desktop is a method called onInit this will be called when the plugin is initially added to a babblevoice desktop and then subsequently when the browser is opened after someone has installed it. advice If you intend to have a gui for your plugin you probably want to call createElement from your onInit to make you icon appear in the toolbar at all times

call events

onNewCall Parameters - call_obj(obj), device(string) - example : {calledid: “2006”, callerid: “2005”, calleridname: “2005”, callstart: 1397552944, direction: “outbound”, uuid: “97d0348c-c47d-11e3-b60e-870cde3b5b85”}, “2005@omniis.babblevoice.com” call_obj - call_obj device - the device the call is in relation too Description Called at the start of a call advice if you are looking to screen pop or grab info when a call starts this is where you want to do this be aware this is called when any call starts (whether it is the main user or not) it might be more suitable for you to check the device against the main user using getMainUser – you might want to restrict this further to stop hordes of api requests for screen popping.

onCallConnected

Parameters - call_obj(obj), device(string) - example : {calledid: “2006”, callerid: “2005”, calleridname: “2005”, callstart: 1397552944, direction: “outbound”, uuid: “97d0348c-c47d-11e3-b60e-870cde3b5b85”}, “2005@omniis.babblevoice.com” call_obj - call_obj device - the device the call is in relation too Description called when a ringing call has connected

onCallHangup

Parameters - call_obj(obj), device(string) - example : {calledid: “2006”, callerid: “2005”, calleridname: “2005”, callstart: 1397552944, direction: “outbound”, uuid: “97d0348c-c47d-11e3-b60e-870cde3b5b85”}, “2005@omniis.babblevoice.com” call_obj - call_obj device - the device the call is in relation too Description Called when a call has ended advice there are two things you likely want to do from here, close any alerts made from alertTaskBar for a call, or make api requests to send info from the completed call

call_obj

This is the obj we pass through with each of the above methods of your plugin Attributes

  • uuid - (string) the uuid of the call in the format “e1ghtchr-f0ur-f0ur-4chrs-twelvechar5s”
  • direction - (string) the direction of the call the possibilities for this are : “inbound” or “outbound”
  • callerid - (string) the caller id of the outbound call leg
  • calleridname - (string) this is a session variable which contains a parsed name for the caller id be aware many providers do not set this so sometimes this can be a blank string
  • calledid - (string) the number called to start the call
  • callstart - (number) the time in epoch format this is a useful site for anyone who has not worked with epoch before, it even has ways to convert to and from it in javascript

babblevoiceDesktopApi

createElement

Parameters

  • icon(string)
  • tooltip(string)
  • html(string)
  • callback(function)
  • onOpen(function)
  • second_img(string)

example : “http://url.to/your/image", “example”, “some HTML or Text”, doStuff, openAndPopulate, “http://url.for/a/rollover/image"

icon

This can be a url to an image in a html accepted format or a font from this library for example “icon-phone” advice Font Awesome is awesome and you should use and support it’s development be aware we currently only support the 3.2.1 icons and formats although at some point in the future we will upgrade and do what we can to stop this breaking your plugin icons

tooltip

This is the text displayed when the user hovers over the icon

html

This is any html or plain text you wish to display when the button is clicked, advice if you don’t want this to happen and just run an onOpen pass through false instead of the html parameter

callback

This is a function to be called when the the user either clicks the return button of double clicks off the html window with your html in advice this callback will be where you want to save any data from you popup be aware if a user closes the pop up of the extension by clicking in the browser window or the extension icon in the browser then this event will not be fired.

onOpen

This will be called when the user clicks you icon in the toolbar advice this will allow you to dynamically edit your html be aware - this does not replace the creation of the window for your html they are both called.

Second_img

This is a url to a second image for a rollover effect on the toolbar be aware if you are using the Font Awesome library then this can be omitted as the rollover will be the same as the standard icons in the toolbar (grey then black on mouse over).

Description

This method will add a button to the babblevoice desktop toolbar for you it needs to be called each time the browser is opened.

getElementFromMyHtml

Parameters - id(string) - example : “idOfMyElement”

Description

This method will find and return an element object of an element with the id passed to it which is in the html that you create in createElement

Example usage

The following example methods will add an icon to the toolbar and when clicked it will create a popup containing a div with no content then the onOpen will set the innerHTML of the div to test

this.onInit = function(){
    babblevoiceDesktopApi.createElement('icon-phone', 'example', '<div id="example-test"></div>', function(){}, this.getElementExample);
}
this.getElementExample = function(){
    var div = babblevoice.getElementFromMyHtml('example-test');
    div.innerHTML = 'test'
}

getMainUser

Parameters - none

Description

This method returns the current main user as a string for example : “2005@omniis.babblevoice.com”

removeElement Parameters - id(string) - example : “idOfMyElement”

Description

This method is used to remove a toolbar icon added by you plugin. this is useful if you want to change html you added with #createElement or to remove a button added to quickly call a function be aware this method can only be called from a method of your plugin not anonymous functions

Parameters

  • number(string)
  • phone(string)

example : “2006”, “2005@omniis.babblevoice.com”

number - this is the number to dial

phone - this is the phone to call the number from

Description

The call method allows your plugin to easily use the babblevoice api to make a call from you plugin

Example Usage

This example shows the three options for the for the phone parameter, 2006 can be any internal extension or any phone number. in the first line, the main user will call 2006, in the second extension 2005 will call 2006 and the same in the third.

babblevoiceDesktopApi.call('2006')
babblevoiceDesktopApi.call('2006', '2005')
babblevoiceDesktopApi.call('2006', '2005@omniis.babblevoice.com')

xfer

Parameters - call_uuid(sting), desination(string) - example: “fakeuuid-fora-nexa-mple-donotusethis”, “2006” call_uuid - the uuid of the call to be transferred advice this will most likely be retrieved from the call_obj

destination - a string containing an internal extension or any number to forward the call out of the system or to another number within babblevoice. for example : “2006” or “01234567890”

###Description

You can use the xfer method to transfer a call currently connected to the main user to another device or to a full phone number be aware only calls for the main user can be transferred using this method. Also calls can only be transferred once they are connected.

Example usage

The first example will transfer the call with the uuid of 97d0348c-c47d-11e3-b60e-870cde3b5b85 to extension 2006, the second will transfer the call to 01234567890

babblevoiceDesktopApi.xfer('97d0348c-c47d-11e3-b60e-870cde3b5b85', '2006')
bablevoiceDesktopApi.xfer('97d0348c-c47d-11e3-b60e-870cde3b5b85', '01234567890')
this.onCallConnected = function(call_obj, device){
    if(device = babblevoiceDesktopApi.getMainUser()){
    //this will check if the call is in relation to the main user (which is the only device we can xfer from)
        if(call_obj.direction == "outbound"){
/*you probably want to do more checking to make sure it is a call you want to xfer but this example will make a permanent forwarder
to another device once the other end picks up*/
            bablevoiceDesktopApi.xfer(call_obj.uuid, this.toXferTo)
        }
    }
}

getNumberOfWatchDevices

Parameters - none

Description

This method is used to return the number of watch devices the bablevoice desktop is currently watching. It returns a number and can be useful for planning gui elements as the height of the extension popup depends on the amount of devices. be aware this does not include the main user

alertTaskBar

Simple Alert

Parameters - icon(string), title(string), text(string), timeout(number)[optional], clickCallBack(function)[optional] - example - “http://url.to/an/icon", ‘This is a notification’, ‘this is the body of the notification’, 10, function(){console.log(‘was clicked’)}

icon - this is a link to an icon to display on the notification

title - the title portion of the alert box

text - this is the body of your notification

timeout - an amount in seconds to remove the alert after

clickCallBack - a callback function when the alert box is clicked

Description

This method can be used to display information to the user when they do not have the chrome extension popup open, or even if they do. The Simple Alert version is a simplified wrapper of the complex and is we have added to make alerting the user to events nice and easy. Complex Alert Parameters - object(object), id(string), callBack(function), timeout(number)[optional] - example : {objectAsDefined : here}, “This is a notification”, function(){like this}, 10

object - this is an object which is in this format

id - this will become the id of your alert advice if you are using the chrome.notifications format be sure to make the id unique as if there is a notification already active with the id you give the second will not be shown.

callBack - this is only used if you have buttons on your alert box, and if so then this is where you handle the clicking of these, see here for usage advice if you do not want to include a callBack, or you have no buttons then this you can pass through anything (string, false, an empty function…)

timeout - a number in seconds to keep the alert alive for be aware the timeout removes the alert and with the complex alerts after roughly 8 seconds the alert will hide into the chrome notification centre of the task bar

Description

The complex complex alerts allow a lot more interaction and if you play around you will be able to find many more uses than we have.

Example Usage

The first example is for creating a simple alert box. which will look like this

and stay on screen for 20 seconds.

The second Example will create exactly the same alert using the complex alert system.

babblevoiceDesktopApi.alertTaskBar('favicon.png', 'this is the title', 'this is the body', 20)
babblevoiceDesktopApi.alertTaskBar({title: 'this is the title', message : 'this is the body', type:'basic', iconUrl : 'favicon.png'},'id', false, 20)

This next example shows how to create an alert with two buttons and a callback to retrieve input from these. it will long like this

//define a method of our plugin : notificationId and buttonIndex will passed in from the event for the alert
this.callBackForAlert = function(notificationId, buttonIndex){
    //the first thing you probably want to do, is to remove the alert otherwise the alert will remain on screen until the user clicks close, but you might want this.
    babblevoiceDesktopApi.closeAlert(notificationId)
    //check that the alert is the one we want
    if(notificationId == "IDforAlert"){
        //check which button was pressed
        if(buttonIndex = 0){
            //do stuff
            babblevoiceDesktopApi.call(this.toCall);
        }
    }
}

//by binding the callback to our plugin we can access properties of our object, in this example we want the toCall attribute
var callBack = this.callBackForAlert.bind(this)
babblevoiceDesktopApi.alertTaskBar({type: 'basic', message : 'this is the body and below are two clickable buttons which will fire the callback listener', title : "Example", iconUrl : "favicon.png", buttons : [{title :"button0"}, {title : "button1"}]}, "example", callBack )

closeAlert

Parameters - notification(string/notificationObject) - example : “notificationId”, notification_Object

notification - string - this will be in the case of using the complex alert and will be the notification id you give it when you call alertTaskBar

notification - object - this is a notification object which will be used in the case of using simple alert this is returned by alertTaskBar

Description

This method lets you close alerts made from the alertTaskBar method.

unixTime

Parameters - none

Description

As your plugin and the extension runs in context of the local machine, and the data coming in is from our servers which will more than likely have a different time. so this method is used to get the current time of the servers to help keep everything in sync. be aware the time is returned in unix time/ epoch and this link will help you if you haven’t came across this before.

setName

Parameters - number(string), name(string) - examples : “01234567890”, “Garry from that company” number - this is the number you want to change. name - the name you want to replace the number parameter with.

Description

This method is useful and allows for custom name replacement. this is very useful for integration with CRM applications or any other contact API’s. In the example parameter case above any time 01234567890 would be used in the babblevoice desktop, it would be replaced with “Garry from that company” be aware this method will change all instances of the number, even if it is not for the main user and any future instances in the current browser session.

storage

Parameters - property(string), value(string) - examples : “employee”, ‘Dave’

property - this is the property name, to index the value

value - this is used for setting the value of the property.

Description

This is used for storage of data between browser sessions, to set a value include both property and value, to retrieve a stored value just pass through the property parameter, see example below. be aware all values are stored as strings, if you need to store other data types in babblevoiceDesktopApi.storage then you will need to convert the value to a usable format for example, to store arrays we like to use comma separated value strings, so a split(‘,’) will give us the array again.

Example Usage

In the following example we save a value in storage then retrieve it from storage, which we can then use in anyway we want. in the example the main user will call 2006

//set the storage property toCall as '2006'
babblevoiceDesktopApi.storage('toCall', '2006')
//retrieve the value from storage using the property parameter without a value
var valFromStorage = babblevoiceDesktopApi.storage('toCall')
//use our retrieved data
babblevoiceDesktopApi.call(valFromStorage)

LoadExternalScript

Parameters - source(string), type(string) - examples : “http://www.here.com/is/my/script.js", “text/javascript”

Source - a url to a script to load

Type - the type of the script, the same format as a html script tag

Description

Used to load an external script to the babblevoice Desktop, the user will be prompted with a confirm box, to confirm that they want the file loaded.

More information about

Also, check out the babblevoice University on Youtube or ask a question in our Google Group.