Ringover SDK

Import easily the ringover web app iframe into your own project (like your crm)

You need a ringover account to properly use the following features.

Installation

Standalone file is available on:

https://webcdn.ringover.com/resources/SDK/1.1.3/ringover-sdk.js

Also the package is available on npm as ringover-sdk

https://www.npmjs.com/package/ringover-sdk

Setup

Browser

<script  src="ringover-sdk.js"  type="text/javascript"></script>

const  simpleSDK = new  window.RingoverSDK();
// ...

Node.js

npm install --save ringover-sdk

const RingoverSDK = require("ringover-sdk");
const simpleSDK = new RingoverSDK();
// ...

ES6 / Webpack

import RingoverSDK from "ringover-sdk";
const simpleSDK = new RingoverSDK();

// ...

AMD

require(["ringover-sdk"], function(RingoverSDK) {
    const simpleSDK = new RingoverSDK();
    //...
});

Usage

// Set options
const options = {animation: false, size: "auto"};

// Create instance
const simpleSDK = new window.RingoverSDK(options);

// Generate iframe
simpleSDK.generate();

// Set event
simpleSDK.on("ringingCall", (e) => console.log("Call with from number: " + e.data.from_number);

// Check iframe status
simpleSDK.checkStatus();

Configuration

new RingoverSDK({

	// "fixed", "relative", "absolute"
	type: "fixed",
	
	// "big", "medium", "small", "auto"
	size: "medium",
	
	container: null,
	
	position: {
		top: 	null,
		bottom: "50px"
		left: 	null,
		right: 	"50px"
	},
	
	// true, false
	border: true,

	// true, false
	animation: true,

	// "rgb(0,0,0)", "#eee", "red"
	backgroundColor: "transparent",

	// true, false
	trayicon: true,

	trayposition: {
		top: 	null,
		bottom: "10px"
		left: 	null,
		right: 	"10px"
	},
});

new RingoverSDK({options})

All option properties are optional.

Options

type: string

• CSS position type.
• Can be one of the following : ["fixed", "relative", "absolute"].
• Default is "fixed".

size: string

• Size of iframe.
• Can be one of the following : ["big", "medium", "small", "auto"].
• Default is "medium".
  • big: L: 1050px, H: 750px
  • medium: L: 380px, H: 620px
  • small: L: 350px, H: 500px
  • auto: L: 100% of container, H: 100% of container

container: string

• Element id of container.
• Default is null.
• If the container is null the document.body is chosen by default.

position: object

• Object of css position:
  • position.top: string
  • position.bottom: string
  • position.left: string
  • position.right: string
• If size is "auto" or "big" or if container is filled, default position value is {top: "0", left: "0"}
• If size is "medium" or "small", default position value is {bottom: "0", right: "64px"}

backgroundcolor : string

• Choose your background iframe color (only visible if trayicon is enable)
• Can be any CSS background color format in string
• Default is "transparent"

border: boolean

• Choose if you want to display the border of the iframe.
• Default is true.

animation: boolean

• Choose if you want to have an animation when the iframe shows and hides
• Default is true.

trayicon: boolean

• Choose if you want to display a button to show and hide the iframe.
• Default is true.

trayposition: object

• Object of css position:
  • position.top: string
  • position.bottom: string
  • position.left: string
  • position.right: string
• If the container is null, default position value is {bottom: "10px", right: "10px"}
• If the container is not null , default position value is {bottom: "-42px", right: "-42px"}

API

const simpleSDK = new RingoverSDK();

// Iframe main methods
simpleSDK.generate();			// iframe element
simpleSDK.destroy();			// boolean
simpleSDK.checkStatus();		// boolean

// Display methods
simpleSDK.show();			// boolean
simpleSDK.hide();			// boolean
simpleSDK.toggle();			// boolean
simpleSDK.isDisplay();		// boolean

// Ringover methods
simpleSDK.logout();									// boolean
simpleSDK.reload();									// boolean
simpleSDK.getCurrentPage();							// string(pageName) | boolean(false)
simpleSDK.changePage("settings");					// boolean
simpleSDK.dial("+33179757575");						// boolean
simpleSDK.sendSMS("+33610001000", "Hello");			// boolean
simpleSDK.openCallLog("616626881427127983");		// boolean

// Events

simpleSDK.on('changePage',    (e) => console.log(e.data));
simpleSDK.on('dialerReady',   (e) => console.log(e.data));
simpleSDK.on('login',         (e) => console.log(e.data));
simpleSDK.on('logout',        (e) => console.log(e.data));
simpleSDK.on('ringingCall',   (e) => console.log(e.data));
simpleSDK.on('answeredCall',  (e) => console.log(e.data));
simpleSDK.on('hangupCall',    (e) => console.log(e.data));
simpleSDK.on('smsSent',    	  (e) => console.log(e.data));
simpleSDK.on('smsReceived',   (e) => console.log(e.data));
simpleSDK.off();

Methods

generate()

Create an iframe, place it in the DOM and return it.

Return: iframe element

destroy()

Remove iframe from the dom and destroy it. Return true if successful, return false if an error occurs.

Return: boolean

checkStatus()

Returns true if the iframe can be generated or is already in the DOM, returns false if an error occurs.

Return boolean

show() | hide() | toggle()

Show or hide the iframe (if animation: true, the animation is triggered).

Return boolean

isDisplay()

Return true if the iframe is displayed, return false if the iframe is hidden.

Return boolean

logout()

Logout the current user connected to the web app in the iframe. Return true if successful, return false if an error occurs.

Return boolean

reload()

Reload the web app in the iframe. Return true if successful, return false if an error occurs.

Return boolean

getCurrentPage()

Get the current web app page. Return false if an error occurs.

Return (string|boolean)

changePage(pageName)

Change the current web app page. Return true if successful, return false if an error occurs.

Parameters:

• pageName: (string). Example: "dialer", "call-logs", "sms", "settings"...

Return boolean

dial(numberE164, fromNumberE164)

Call a specific number in the web app. Return true if successful, return false if an error occurs.

Parameters:

• numberE164: (string|integer). Example: "+16467129500", "442038906606", 33179757575...
• fromNumberE164: (string|integer). OPTIONAL Must be one of the numbers in the dialer presentation number list. Example: "+16467129500", "442038906606", 33179757575...

Return boolean

sendSMS(toNumberE164, content, fromNumberE164)

send an sms to a specific recipient from a mobile number. Return true if successful, return false if an error occurs.

Parameters:

• toNumberE164: (string|integer). Example: "+16467129500", "442038906606", 33179757575...
• content: (string). Example: "Hello, welcome to our service."...
• fromNumberE164: (string|integer). OPTIONAL Example: "+16467129500", "442038906606", 33179757575...

Return boolean

openCallLog(call_id)

Open a specific call log by its call_id identifier. Return true if successful, return false if an error occurs.

Parameters:

• call_id: (string). Example: "616626881427127983"...

Return boolean

on(eventName, myFunction)

Set a specific event listener to set up a function that will be called when the event is delivered. Return true if successful, return false if an error occurs.

Parameters:

• eventName: (string). Example: "login", "dialerReady", "ringingCall", "changePage"... See below.
• myFunction: (function).

Return boolean

off()

Remove all event listerners previously setted. Return true if successful, return false if an error occurs.

Return boolean

Events

changePage

Trigger a hook when the web app changes page. Return the new page name.

Return object:

{
	action: "changePage",
	data: {
		page: "settings"
	}
}

• page: (string). Example: "dialer", "call-logs", "sms", "settings"...

dialerReady

Trigger a hook when the web app is ready to receive and make call. Return the current user id.

Return object:

{
	action: "dialerReady",
	data: {
		userId: 123
	}
}

• userId: (integer).

login

Trigger a hook when the user logs on the web app. Return the current user id.

Return object:

{
	action: "login",
	data: {
		userId: 123
	}
}

• userId: (integer).

logout

Trigger a hook when the user logs out the web app. Return the previous user id.

Return object:

{
	action: "logout",
	data: {
		userId: 123
	}
}

• userId: (integer).

ringingCall

Trigger a hook when a call is ringing or is being dialed. Automatically open the iframe. Return data call.

Return object:

{
	action: "ringingCall",
	data: {
		direction: "out", // "in"|"out"
		from_number: "fromNumber", 
		to_number: "toNumber", 
		internal: false, // true|false 
		call_id: "123", 
		ringDuration: 0, 
		callDuration: 0
	}
}

• direction: (string). Direction (context) of the call. Value can be "in" or "out".
• from_number: (string). Caller E164 number.
• to_number: (string). Callee E164 number.
• internal: (boolean). True if the call is internal of the team (inter-users), false is the call is external.
• call_id: (string). Identifier of the call.

answeredCall

Trigger a hook when a call is ringing or is being dialed. Return data call.

Return object:

{
	action: "answeredCall",
	data: {
		direction: "out", // "in"|"out"
		from_number: "fromNumber", 
		to_number: "toNumber", 
		internal: false, // true|false 
		call_id: "123", 
		ringDuration: 123, 
		callDuration: 0
	}
}

• direction: (string). Direction (context) of the call. Value can be "in" or "out".
• from_number: (string). Caller E164 number.
• to_number: (string). Callee E164 number.
• internal: (boolean). True if the call is internal of the team (inter-users), false is the call is external.
• call_id: (string). Identifier of the call.
• ringDuration: (integer). Duration in seconds of the ringing time (before answer).

hangupCall

Trigger a hook when a call is ringing or is being dialed. Return data call.

Return object:

{
	action: "hangupCall",
	data: {
		direction: "out", // "in"|"out"
		from_number: "fromNumber", 
		to_number: "toNumber", 
		internal: false, // true|false 
		call_id: "123", 
		ringDuration: 123, 
		callDuration: 123
	}
}

• direction: (string). Direction (context) of the call. Value can be "in" or "out".
• from_number: (string). Caller E164 number.
• to_number: (string). Callee E164 number.
• internal: (boolean). True if the call is internal of the team (inter-users), false is the call is external.
• call_id: (string). Identifier of the call.
• ringDuration: (integer). Duration in seconds of the ringing time (before answer).
• callDuration: (integer). Duration in seconds of the call time (after answer).

smsSent

Trigger a hook when a sms is sendend. Return information about the sms.

Return object:

{
	action: "smsSent",
	data: {
		conversation_id: "123"
		to_number: "toNumber", 
		message: "Hello World",
	}
}

• conversation_id: (string). Identifier of the conversation.
• to_number: (string). SMS Recipient E164 number.
• message: (string). Content of the message.

smsReceived

Trigger a hook when a sms is received. Return information about the sms.

Return object:

{
	action: "smsReceived",
	data: {
		conversation_id: "123"
		from_number: "fromNumber", 
		message: "Hello World",
	}
}

• conversation_id: (string). Identifier of the conversation.
• from_number: (string). SMS Sender E164 number.
• message: (string). Content of the message.

License

Apache-2.0