Table of contents
- Key Benefits
- Installation
- Core Module
- Helpers
- Performing a RingOut
- Call Management Using JavaScript
- SMS
- Page Visibility
- Tracking Ajax Requests
- Model Relations
Key Benefits
- Automatically handles token lifecycle procedures in multi-tab environment
- Re-issues non-authorized requests
- Decrypts PUBNUB notification messages
- Parses multipart API responses
- Provides a broad variety of helper functions to work with API requests and responses
Installation
SDK can be used in 3 environments:
1. Set things up in Browser
1.1. Get the code
Pick the option that works best for you:
-
Preferred way to install SDK is to use Bower, all dependencies will be downloaded to
bower_components
directory:bower install rcsdk --save -
Download the bundle version, which includes PUBNUB and ES6 Promise (choose which works best for you):
-
Donwload everything manually (not recommended):
1.2.a. Add scripts to HTML page
You can use bundle version (with PUBNUB and ES6 Promise included in main file).
Add this to your HTML:
Another option is to add dependencies and SDK separately.
Add this to your HTML (order should be preserved):
<!-- or rc-sdk.min.js -->
Preferred way is to use RequireJS or bundle version of SDK.
1.2.b. Set things up in Browser (if you use RequireJS in your project)
// Add this to your RequireJS configuration filerequire; // Then you can use the SDK like any other AMD component;
2. Set things up in NodeJS
-
Install the NPM package:
npm install rcsdk --save -
Require the SDK:
var RCSDK = ;
3. Set things up for Browserify or Webpack (experimental)
This is an experimental support, things may change in 1.3.0
-
Install the NPM package:
npm install rcsdk --save -
Require the SDK:
var RCSDK = ; -
Add the following to your
webpack.config.js
, path should be relative to Webpack configuration file:externals:'xhr2': 'XMLHttpRequest''dom-storage': 'localStorage'resolve:alias:'pubnub': path
To reduce the size of your Webpack bundle it's better to use browser version of PUBNUB (instead of the one that is
installed via NPM along with the SDK). You can get PUBNUB via Bower or directly download the the source.
More information can be found in installation for browser. Also it's not needed to use
NPM's xhr2
and dom-storage
packages since both objects exist in browser by default, so they can be externalized.
Core Module
Instantiate the RCSDK object
The SDK is represented by the global RCSDK constructor. Your application must create an instance of this object:
In order to bootstrap the RingCentral JavaScript SDK, you have to first get a reference to the Platform singleton and then configure it. Before you can do anything using the Platform singleton, you need to configure it with the server URL (this tells the SDK which server to connect to) and your unique API key (this is provided by RingCentral's developer relations team).
var rcsdk = server: 'https://platform.devtest.ringcentral.com' // SANDBOX //server: 'https://platform.ringcentral.com', // PRODUCTION appKey: 'yourAppKey' appSecret: 'yourAppSecret';
This instance will be used later on to perform calls to API.
Get the Platform Singleton
var platform = rcsdk;
Now that you have your platform singleton and SDK has been configured with the correct server URL and API key, your application can log in so that it can access the features of the API.
Login
Login is accomplished by calling the platform.authorize()
method of the Platform singleton with username, extension
(optional), and password as parameters. A Promise
instance is returned, resolved with an AJAX Response
object.
platform;
Handling Login Success
Because the login process is asynchronous, you need to call the promise's then
method and pass your success handler as
the continuation function.
This function will be called once login has succeeded, which allows the application to then perform updates to the user interface, and then perform the next actions using the API to load account details for the user's account and such.
Handling Login Failure
Login can, of course, fail - a user can enter the incorrect password or mistype their user name.
To handle cases where login fails, you can provide an error handler function in a call to the promise's catch
method.
To keep this example simple, a simple JavaScript alert is being used. In a real application, you will want to provide
a good UX in your login form UI.
Checking Authentication State
To check in your Application if the user is authenticated, you can call the isAuthorized
method of the platform
singleton:
platform;
The SDK takes care of the token lifecycle. It will refresh tokens for you automatically. It will also automatically pause and queue all new API requests while the token is being refreshed in order to prevent data loss or inconsistency between SDK instances in different tabs. Paused / queued API requests will then be automatically processed once the token has been refreshed. All apropriate events will be emitted during this process.
If you just need to check whether the user has a valid token, you can call the isTokenValid
method:
platform; // returns boolean
Performing API calls
To perform an authenticated API call, you should use the apiCall
method of the platform singleton:
platform;
You can also use short-hand methods:
platform;platform;platform;platform;
Take a look on sms example to see how POST request can be sent.
Important note for users of versions prior to 1.2.0:
AjaxOptions now has body
and query
properties instead of post
and get
respectively. You can continue to use old
post
and get
properties, backwards compatibility is maintained, but they both were deprecated since 1.2.0.
If application send both body
and post
or query
and get
at the same time then post
and get
will be ignored.
Sending things other than JSON
You can set headers['Content-Type']
property of AJAX options to false
in order to let XHR library to figure out
appropriate Content-Type
header automatically.
Important notes:
- Automatic guessing of
Content-Type
is unreliable, if you knowContent-Type
then set it explicitly - NodeJS cannot set
multipart/mixed
header with appropriate boundary automatically when sendingBuffer
object so your application must take care of that
Logout
Logging the user out is trivial - just call the logout
method on the platform singleton:
platform;
Events
The platform provides the following events:
accessViolation
- emitted when the application attempts to make an API call when there is no valid access token or the refresh process has failed, which may occur when the user switches tabs in the browser.logoutSuccess
logoutError
authorizeSuccess
authorizeError
refreshSuccess
refreshError
To listen on platform events, you should call the on
method of the platform singleton:
platform;
The on
method accepts an event type as its first argument and a handler function as its second argument.
Subscriptions
Subscriptions are a convenient way to receive updates on server-side events, such as new messages or presence changes.
Subscriptions are created by calling the getSubscription
method of the RCSDK instance created earlier on.
var subscription = rcsdk; subscription; subscription;
Once a subscription has been created, the SDK takes care of renewing it automatically. To cancel a subscription, you can
call the subscription instance's destroy
method:
subscription;
You can add more events to the same subscription at any time, by calling the subscription's addEvents
method:
subscription;subscription;
It is recommended to use appropriate Helpers.
Subscriptions Lifecycle
The number of active subscriptions is limited per account (about 20). This means that the application should dispose of unused subscriptions in the following situations:
- the user navigates away from the page or particular view
- the
Platform
instance emitslogoutSuccess
oraccessViolation
events - a subscription becomes unused by the application, based upon the application's business logic
Following is an Angular-specific example, showing controller code that listens to subscriptions:
var platform = rcsdk; { // In order to release a subscription, you need to remove it at the server // A simple token check will not result in a refresh process, as opposed to platform.isAuthorized() if platform subscription; // Detach event listeners subscription; } window; // listener has to be SYNCHRONOUS platform; // This occurs when user navigates away from the controller$scope;
Helpers
Abstract
The SDK provides a variety of different helpers to make it easier to alter, save, load, and delete data objects and otherwise interact with the features of the API. Helpers are plain JavaScript objects that contain functions and useful properties (e.g. constants).
Basic Functionality
All helpers are extensions to the base Helper
object and have all of its functions, plus some overrides and extra
functionality. See the documentation for each particular helper for information on available options and methods.
Following is a deeper look at the CallHelper
object.
Create a URL
rcsdk;
Creates a URL that can be provided to the Platform#apiCall()
method. Creation algorithm is based on options:
{personal: true}
- Call log of the currently logged in extension{extensionId: '12345'}
- Call log of extension with the id12345
(the logged in user must have admin permissions)
Following are some example calls, along with the URLs that they would return:
rcsdk; // '/account/~/extension/~/call-log'rcsdk; // '/account/~/extension/~/call-log'rcsdk; // '/account/~/extension/12345/call-log'rcsdk; // '/account/~/extension/12345/call-log/67890'
Check if an object exists on the server
rcsdk;
If the object exists on the server, then the isNew
method will return false. The object is considered not new if it
has both ID and URI properties - this usually means that the object was returned from the server.
rcsdk; // falsercsdk; // falsercsdk; // falsercsdk; // true
Filter an array of objects
rcsdk;
CallHelper#filter(options)
returns a preconfigured function that can be used for the fn
argument when calling the
filter
method (Array.prototype.filter(fn)
) on an array of calls. The behavior of the filter may vary depending on
the options
argument.
// calls in an array of Call Log callsvar callsFilteredByDirection = calls;var callsFilteredByType = calls;
Sort an array of objects
rcsdk;
CallHelper#comparator(options)
returns a preconfigured function that can be used for the fn
argument when calling
the sort
method (Array.prototype.sort(fn)
) on an array of calls. The behavior of the filter may vary depending on
the options
argument. By default, values are extracted simply as item[options.sortBy]
as strings and sorted as
strings. Custom options.extractFn
and options.compareFn
functions may be specified.
// calls in an array of Call Log callsvar callsSortedByStartTime = calls; // or any other propertyvar callsSortedByDuration = calls; // or any other property // filter and sort can be combinedvar inboundCallsSortedByStartTime = calls ;
Special methods - Get pre-configured Subscription objects for endpoints
These methods will provide Subscription
objects with pre-bound events.
var subscription = rcsdk;
var subscription = rcsdk;
Once you have a Subscription
object, all you need to do next is register it by calling its register
method:
subscription;
Special methods - Convert ActiveCalls array of Presence into regular Calls
Assume that presence
is an object returned by one of Presence endpoints.
var calls = rcsdk;
Full Example
For this example, AngularJS will be used.
var platform = rcsdk Call = rcsdk; $scopecalls = ;$scopenextPageExists = true;$scopequeryParams = page: 1 perPage: 'max'; // page and perPage may be set from template $scope { // can be called from template to request next page $scopequeryParamspage++; ;}; { platform; } ;
Performing a RingOut
This example demonstrates a way to create a flexible RingOut tracking procedure. This is the most complex example with maximum fine-tuning - it could be simplified to suit the business requirements.
The sequence of RingOut is as follows:
- Perform a POST with the RingOut data
- Poll the RingOut status (GET requests) every second or so
Please refer to the following example:
var platform = rcsdk Ringout = rcsdk // this is the helper Utils = rcsdk Log = rcsdk timeout = null // reference to timeout object ringout = {}; // this is the status object (lowercase) /** * @param */ { Log; ; } { platform ; } /** * @param {function(number?)} next - callback that will be used to continue polling * @param */ { if !Ringout return; platform ; } /** * To stop polling, call this at any time */ { Utils; if Ringout platform ; // Clean Ringout; } /** * Start the ringout procedure (may be called multiple times with different settings) */;
Utils.poll()
and Utils.stopPolling()
methods
A deeper look at the // first, define polling function: { if condition ; // uses previous delay, condition can be anything required to keep polling // or next(100); -- simply sets a new delay // or next(delay * 2); -- this will make delay bigger after every cycle // if next() is not called, then next cycle will not happen} // then start polling// pollFn -- (required) is function that will be called to track status// 500 -- (optional) is a number of milliseconds is to delay the next poll// previousTimeout -- (optional) can be supplied to automatically cancel any previous timeouts// newTimeout will be returnedvar newTimeout = Utils; // call this at any time to stop pollingUtils;
Call Management Using JavaScript
If you are integrating with a CRM or ERP system, use of the JavaScript SDK is highly recommended. Following is an example of a call management integration that includes monitoring of incoming calls and performing of RingOuts.
A call management integration usually consists of the following tasks:
- Track the telephony status
- View the list of active calls
- View the recent calls
Track the telephony status
First, you need to load the initial Presence status:
var platform = rcsdk Presence = rcsdk accountPresence = {}; platform;
In the meantime, you can also set up Subscriptions:
var subscription = Presence; subscription; subscription; return subscription;
View the list of active calls
var activeCalls = Call = rcsdk; // This call may be repeated when needed, for example as a response to incoming Subscriptionplatform
View the list of recent calls
var calls = Call = rcsdk; // This call may be repeated when needed, for example as a response to incoming Subscriptionplatform;
By default, the load request returns calls that were made during the last week. To alter the time frame, provide custom
query.dateTo
and query.dateFrom
properties.
SMS
In order to send an SMS using the API, simply make a POST request to /account/~/extension/~/sms
:
var platform = rcsdk;platform;
Page Visibility
This class is a wrapper for the Page Visibility API, which hides vendor prefixes and provides a short and simple way to observe visibility changes.
This allows tracking the visibility of the page/tab/window/frame so that the application can react accordingly. Following are some actions that the application may wish to take whenever it becomes visible:
- Check authentication
- Reload/resync time-sensitinve information from the server
- Send heartbeats to the server
Another usage is to reduce the number of Call Log or Messages reloads when the application is not visible. The SDK does not require that any such optimizations be implemented in the application, but it is considered good practice.
Using the page visibility wrapper is very straightforward - just register an observer function for the
visibility.events.change
event:
var visibility = rcsdk; visibility;
See also Core Module: Checking Authentication State.
Alternatives
You can use any of the libraties that work with the Page Visibility API, such as visibility.js.
Tracking Ajax Requests
You can set up tracking for all Ajax requests (for instance, to log them somewhere) by obtaining an Ajax observer object and registering observers on its various events:
var observer = rcsdk;observer;observer;observer;
Observer functions are passed a reference to the Ajax for which the event has occurred. Every Ajax object offers a number of accessor methods and properties:
options
— request that was given to transportresponse
— raw text response from server (if any)status
— HTTP status code (if any)headers
— HTTP response headers (if any)
Model Relations
Abstract
The SDK allows easy establishment of relationships between objects, such as between a Message object and its associated Contact objects, or a Presence object and its associated Extension object. How the relationship is resolved varies across different types of objects. The resolving function is provided by helper objects of a certain type.
Relationship
Models have relationships to other models.
In many cases, model relationships are merely through properties of a model that identify other models. The data for the associated child models is not contained inside the data for the model and would need to be loaded with separate requests to the server. This type of relationship is considered a weak relationship. To use an example, both the Message and Call models have relationships to the Contact model. Associated models should be loaded separately and may be assigned to appropriate properties dynamically on the client based upon some criteria through helpers.
In some cases, models may actually contain other models. In such cases, the data for the associated child models will be
contained inside the model's data in the form of a property. The server returns the data for the model and its contained
child models within the same API call. As examples of this, the Presence model contains an extension
property and the
Account model contains an operator
property, and these properties are both references to contained models of type
IExtensionShort
.
Examples
Abstract CallerInfo types and Contacts
var contacts = homePhone: '+(1)foo' ... // homePhone may be formatted callerInfos = phoneNumber: '1foo' ...; // phoneNumber is not formatted rcsdk;
Each callerInfo
object will get the new properties:
contact
— matching contactcontactPhone
— entry fromcontact
that matchedphoneNumber
Messages / Calls and Contacts
For Messages and Calls, optimized helper functions may be used:
rcsdk;rcsdk;
This will internally fetch a list of callerInfos
and attach appropriate contacts to them.
Presence and Extensions
Presence
information may be attached to extensions
, for example, when the application has loaded a list of
extensions and a list of their associated presence. Each extension
will be given a new presence
property, which will
link to the presence object for the extension.
rcsdk;