Configuration and Development

Creating a New App SDK Application

By default, App SDK application management is disabled. You’ll have to request your RingCX Digital project manager to grant you the permission to manage them.

In RingCentral's RingCX Digital administration section, you’ll get the « Dev tools » menu section and « Developed applications (SDK) » menu item in the administration and be able to create new ones.

Click on the Add button to start adding your own application.

An application is defined by the following attributes:

Available application modes are:

The best practice is to develop the application in ​development​ mode. When the application seems to be ready, it should be switched to ​pre-production​ mode. Then if everything is working correctly, it has to be switched to production ​mode. Note that to have live refresh of code, it must be in development mode.

Installation

When created, the application m​ust​ be installed in order to make it available on the domain. Installed applications can be found under « Applications » in the « Installed Apps » menu section.

Click on the Install button, choose the application you want to install, and confirm your selection. By default, only certified and local applications are available in the list. Other applications could be installed if you get its installation link.

Once installed, the application can be configured (if the configuration URL has been specified). Look for the gear icon to configure your application.

If the configure button is clicked, an iframe overlay is rendered with the application’s configuration URL plus current domain name as parameter. Example if application configuration URL is http://example.org​ and current domain name is g​oogle, ​the iframe URL will be: http://example.org?domain=google.​

The configuration overlay window aims to set domain dependent settings of the application.

Permissions

An App SDK application could be granted a set of permissions. API calls may require a permission to be set before an API call is allowed. A 403 error will be returned if the application or current user is not granted the proper permission.

By default all permissions are disabled. To enable one or many of them click on the edit permissions icon as shown.

This will bring a pop-up window where you can check the permissions you want your application to have.

If you change the application's permissions, installations are required to update their permission. Navigating to the installations administration section you will see the following message:

Upon clicking the update permissions icon, you will need to confirm you are ready to update the permission of the installed application.

IFrame Messaging

The RingCX Digital App SDK offers iframe rendering features. The main inconvenience with iframes is the communication with the parent window (RingCX Digital).

The RingCX Digital App SDK offers via ​window.postMessage​ method the feature to send messages from an iframe to the RingCX Digital window. You will get more details on how window.postMessage works in this technical review.

Sending a Message to RingCX Digital Window

On the iframe side, here is an example of how to send a message to the RingCX Digital window:

    window.parent.postMessage({
      name: "smcc:foo",
      data: { identityId: "4f0aa52d656a3d75867f784b" }
    }, "http://example.digital.ringcentral.com");

To receive messages in RingCX Digital, first you have to whitelist the iframe sender origin:

    SMCC.Window.acceptPostMessageOrigin("https://example.com");
    SMCC.Window.onPostMessage("foo", function(data, origin) {
      console.log("New data:", data, "from:", origin);
    });

OAuth Authentication

RingCX Digital App SDK provides many ways to render iframes. But, most of the time those iframes must be authenticated. The RingCX Digital’s interface offers a standard ​OAuth 2.0​ provider to request access tokens and get RingCX Digital's current user information.

Prerequisites

First of all, you must get your application’s k​ey ​and s​ecret. Navigate to Dev tools, and then Developed applications (SDK) to get them:

The ​key ​and ​secret ​are mandatory to make OAuth requests. In order to be secure, iframe authentication callbacks should be in HTTPS. Note that all OAuth requests m​ust​ be in HTTPS.

You must also configure a callback URL for the application to a valid one. This will be explained later.

Authentication Process

If you are not familiar with the OAuth 2.0 protocol, here is how authentication works:

1. User agent is not authenticated on application, a redirection is made on the RingCX Digital OAuth provider with the application key and a redirect URL.
2. If the application key is valid, user agent is redirected to the provided redirect URL with authorization code as a parameter. Otherwise the user agent is redirected to the redirect URL with an error parameter.
3. Then, the application must make a POST request with returned code and application secret to get an OAuth access token.
4. with this access token, the iframe can get the current user infos via REST /1.0/users/me​ API method.

Request an OAuth Authorization Code

An OAuth authorization code is required before trying to get an access token. User agent must​ be redirected to the RingCX Digital authorization URL to get it.

URL

    https://<domain-name>.digital.ringcentral.com/oauth/authorize

Response

If every parameter is correct, user agent is redirected to redirect URI with a ​"code"​ parameter:

    https://redirct-uri.com?code=xxx

If authorization fails (user can’t authenticate or does not accept application), user agent is redirected to redirect URI with an ​error ​parameter:

    https://redirect-uri.com?error=authentication_failed

If one of the provided parameters is invalid or missing, a 400 HTTP error is returned with a JSON error as body. Here are all available error responses:

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "client_id"',
 "status": 400
}

{
 "error": "invalid_client_id",
 "message": "Invalid client ID",
 "status": 400
}

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "redirect_uri"',
 "status": 400
}

{
 "error": "invalid_redirect_uri",
 "message": "Invalid redirect URI",
 "status": 400
}

{
 "error": "invalid_redirect_uri",
 "message": "Redirect URI scheme does not match callback URL scheme",
 "status": 400
}

{
 "error": "invalid_redirect_uri",
 "message": "Redirect URI port does not match callback URL host",
 "status": 400
}

{
 "error": "invalid_redirect_uri",
 "message": "Redirect URI port does not match callback URL port",
 "status": 400
}

{
 "error": "invalid_redirect_uri",
 "message": "Redirect URI path does not match callback URL path",
 "status": 400
}

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "response_type"',
 "status": 400
}

{
 "error": "invalid_response_type",
 "message": 'Invalid response type, it must be "code"',
 "status": 400
}

Request an OAuth Access Token

To get an access token you must first get an authorization code (see above). Then when the user agent is redirected to the application (redirect URI), a request must be made by the application to get an access token.

Request

POST https://<domain-name>.digital.ringcentral.com/oauth/token

Response

If all provided parameters are valid, a 200 HTTP response is returned and the access token is rendered in the response body as JSON:

{
  "access_token": "06eaea7ac0e0b4b7ac622e81"
}

Otherwise, if one of the provided parameters is invalid or missing, a 400 HTTP error is returned with a JSON error as body. Here are all available error responses:

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "client_id"',
 "status": 400
}

{
 "error": "invalid_client_id",
 "message": "Invalid client ID",
 "status": 400
}

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "client_secret"',
 "status": 400
}

{
 "error": "invalid_client_secret",
 "message": "Invalid client secret",
 "status": 400
}

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "code"',
 "status": 400
}

{
 "error": "invalid_code",
 "message": "Invalid code",
 "status": 400
}

{
 "error": "expired_code",
 "message": "Expired code",
 "status": 400
}

{
 "error": "missing_parameter",
 "message": 'Missing required parameter: "grant_type"',
 "status": 400
}

{
 "error": "invalid_grant_type",
 "message": 'Invalid grant type, it must be "authorization_code"',
 "status": 400
}

Getting Access Token User Information

When getting an OAuth access token, you’ll be able to get information for this token. An access token is associated to a RingCX Digital agent. To get the agent’s ID, a REST API request (​/1.0/users/me​) must be made by an application.​ P​lease refer to RingCX Digital REST API documentation for more information.