SIGN UP

Quickstart

Loading Web SDK from CDN

Before Web SDK can be used it should be loaded and initialized. Since Web SDK is a javascript library it can be loaded using standard HTML code for embedding javascript library into a web page (usually it's added somewhere before closing HEAD tag):

<script type="text/javascript" src="//cdn.voximplant.com/edge/voximplant.min.js"></script>

Web page should be loaded from HTTPS
Most modern web browsers limit voice and video capture only to web pages loaded over HTTPS. This also means that such page can't be loaded from a local .html file. For development purpose, local files can be self-hosted. Web browsers allow to load self-hosted pages from localhost over HTTP.

Getting started with VoxImplant.Client singleton

VoxImplant.Client is a Singleton class and the main class of the SDK that provides access to VoxImplant's functions, getInstance function is used to receive its instance as shown below:

const voximplant = VoxImplant.getInstance();

After Voximplant javascript library has been loaded it should be initialized using the init method before any other method of the SDK can is called. The optional VoxImplant.Config instance can be passed to the init method in order to configure the SDK. The VoxImplant.Events.SDKReady event will be triggered after the SDK has been successfully initialized. Please see the following example:

const voximplant = VoxImplant.getInstance();
voximplant.addEventListener(VoxImplant.Events.SDKReady, () => {
  // SDK initialized
});
// Add event handler BEFORE calling method for Babel compatibility.
voximplant.init();
const voximplant = VoxImplant.getInstance();
voximplant.init().then(() => {
  // SDK initialized
}).catch(() => {
  // SDK init failure
});
const voximplant = VoxImplant.getInstance();
try {
  await voximplant.init();
  // SDK initialized
} catch (e) {
  // SDK init failure
}

After the SDK is initialized, the connect function should be called to establish a data connection between a browser and the Voximplant Cloud. In the similar manner developer should add the following event listeners: VoxImplant.Events.ConnectionEstablished, VoxImplant.Events.ConnectionFailed, VoxImplant.Events.ConnectionClosed to handle connection events.

voximplant.addEventListener(VoxImplant.Events.ConnectionEstablished, () => {
  // Connection was established successfully
});
voximplant.addEventListener(VoxImplant.Events.ConnectionFailed, () => {
  // Connection failed
});
voximplant.addEventListener(VoxImplant.Events.ConnectionClosed, () => {
  // Connection was closed
});
voximplant.connect();
voximplant.addEventListener(VoxImplant.Events.ConnectionClosed, () => {
  // Connection was closed
});
voximplant.connect().then(() => {
  // Connection was established successfully
}).catch(() => {
  // Connection failed
});
voximplant.addEventListener(VoxImplant.Events.ConnectionClosed, () => {
  // Connection was closed
});
try {
  await voximplant.connect();
  // Connection was established successfully
} catch (e) {
  // Connection failed
}

The last thing that should be done before the call object can be used is authorization: the Application User's username and password should be passed to the login method. The VoxImplant.Events.AuthResult event is triggered to notify about the login result. For better security our SDK also provides two additional login methods: with one-time login keys and with renewable tokens.

voximplant.addEventListener(VoxImplant.Events.AuthResult, event => {
  if (event.result) {
    // Authorization success
  } else {
    // Authorization failure
  }
});
// Change "appname" and "accname" to names of your application and account,
// "username" and "password" to name and password of user created via
// the control panel.
voximplant.login("username@appname.accname.voximplant.com", "password");
// Change "appname" and "accname" to names of your application and account,
// "username" and "password" to name and password of user created via
// the control panel.
voximplant.login("username@appname.accname.voximplant.com",
  "password").then(() => {
  // Authorization success
}).catch(() => {
  // Authorization failure
});
try {
  // Change "appname" and "accname" to names of your application and account,
  // "username" and "password" to name and password of user created via
  // the control panel.
  await voximplant.login("username@appname.accname.voximplant.com",
    "password");
  // Authorization succes
} catch (e) {
  // Authorization failure
}

 

Using VoxImplant.Config to specify SDK settings during the initialization

There are number of settings that can be specified while the SDK initialization, let's review them all one-by-one:

  • micRequired - if set to true, SDK will show microphone access dialog right after the initialization of the SDK. VoxImplant.Events.MicAccessResult event will be dispatched after user allowed or denied access to the microphone.
  • videoSupport - can be used to enable video calls support (for Flash mode only for now)
  • progressToneCounry - Country code in ISO format for progress tone generated automatically if progressTone set to true. Has "US" value by default.
  • progressTone - Automatically plays progress tone by means of SDK according to specified progressToneCountry if set to true.

Please note that SDK currently supports only US and Russian progress tones generated automatically. We will add other countries soon. Meanwhile you can use browser-based audio playback capabilities for that purpose.

The following example shows how the settings can be passed to init function:

voximplant.init({
  micRequired: true,
  progressTone: true,
  progressToneCountry: "US"
});

Making calls

After the SDK was initialized and connected to the Voximplant Cloud it's now time to make your first call. Since the call can end in different ways there is a group of the call events that can be dispatched by the Call class instance. The call function of the VoxImplant.Client class is used to make an outgoing call from the SDK.

const call = voximplant.call("numbertocall");
call.addEventListener(VoxImplant.CallEvents.Connected, event => {
  // event - the instance of VoxImplant.CallEvents.Connected class,
  // use event.call to get the instance of VoxImplant.Call for this call
  // call was connected succesfully
});
call.addEventListener(VoxImplant.CallEvents.Disconnected, event => {
  // event - the instance of VoxImplant.CallEvents.Disconnected class,
  // use event.call to get the instance of VoxImplant.Call for this call
  // call was disconnected
});
call.addEventListener(VoxImplant.CallEvents.Failed, event => {
  // event - the instance of VoxImplant.CallEvents.Failed class, use
  // event.call to get the instance of VoxImplant.Call for this call, or
  // event.code and event.reason to get the status code and the reason of
  // the call failure call failed
});
call.addEventListener(VoxImplant.CallEvents.ProgressToneStart, event => {
  // event - the instance of VoxImplant.CallEvents.ProgressToneStart class,
  // use event.call to get the instance of VoxImplant.Call for this call
  // Event dispatched when progress tone playback starts
});
call.addEventListener(VoxImplant.CallEvents.ProgressToneStop, event => {
  // event - the instance of VoxImplant.CallEvents.ProgressToneStop class,
  // use event.call to get the instance of VoxImplant.Call for this call
  // Event dispatched when progress tone playback stops
});

 

Manage calls

The SDK allows you to make different number of outgoing calls which can be controlled on both SDK and VoxEngine side. There are a few functions to control calls on the SDK side and it's a good idea to have access to each call instance via some variable. The list of the functions is available at VoxImplant.Call page from the Web SDK Reference. Here are just a few simple examples:

call.muteMicrophone(); // don't send audio from microphone to the call
call.sendTone("0"); // send tone for 0 key
call.unmuteMicrophone(); // start sending audio from microphone to the call
call.hangup(); // hangup the call

Receiving calls

First of all, we want to know when there is an incoming call to user connected to the Voximplant Cloud using Web SDK. There is a special event for that - VoxImplant.Events.IncomingCall , adding event listener to the VoxImplant.Client instance lets us handle this event.

VoxImplant.getInstance().addEventListener(
  VoxImplant.Events.IncomingCall, event => {
  // answer the incoming call, or decline() to decline
  // event.call.number() will return Caller ID
  event.call.answer();
});