node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »

purecloud-platform-client-v2


title: JavaScript SDK

A JavaScript library to interface with the PureCloud Platform API

GitHub release Bower version npm

Platform API Javascript Client

Install with Bower:

bower install purecloud-platform-client-v2

Install with NPM:

npm install purecloud-platform-client-v2

Reference from the CDN:

<!-- Replace `6.1.1` with the version you want to use. -->
<script src="https://sdk-cdn.mypurecloud.com/javascript/6.1.1/purecloud-platform-client-v2.min.js"></script>

View the documentation on the PureCloud Developer Center. View the source code on Github.

Usage

Client-side usage

Reference the SDK in your HTML document. For convenience, all modules are bundled together.

<!-- Include the full library -->
<script type="text/javascript" src="purecloud-platform-client-v2.min.js"></script>

NodeJS usage

Require the SDK in your node app. All modules are obtained from the purecloud-platform-client-v2 package.

const platformClient = require('purecloud-platform-client-v2');

Authentication

After authentication has completed, the access token is stored on the ApiClient instance and the access token will be sent with all API requests.

Node.js Client Credentials grant

The Client Credentials grant only works when used in node.js. This is restricted intentionally because it is impossible for client credentials to be handled securely in a browser application.

const platformClient = require('purecloud-platform-client-v2');
var client = platformClient.ApiClient.instance;
client.loginClientCredentialsGrant(clientId, clientSecret)
  .then(function() {
    // Do authenticated things 
  })
  .catch(function(response) {
    console.log(`${response.status} - ${response.error.message}`);
    console.log(response.error);
  });

Web Implicit grant

The Implicit grant only works when used in a browser. This is because a node.js application does not have a browser interface that can display the PureCloud login window.

const platformClient = require('purecloud-platform-client-v2');
var client = platformClient.ApiClient.instance;
client.loginImplicitGrant(clientId, redirectUri)
  .then(function() {
    // Do authenticated things 
  })
  .catch(function(response) {
    console.log(`${response.status} - ${response.error.message}`);
    console.log(response.error);
  });

Any platform Provide an existing auth token

const platformClient = require('purecloud-platform-client-v2');
var client = platformClient.ApiClient.instance;
client.setAccessToken(yourAccessToken);
// Do authenticated things; no login function needed 

Environments

If connecting to a PureCloud environment other than mypurecloud.com (e.g. mypurecloud.ie), set the environment on the ApiClient instance.

const platformClient = require('purecloud-platform-client-v2');
var client = platformClient.ApiClient.instance;
client.setEnvironment('mypurecloud.ie');

Access Token persistence

In a web environment, it is possible to persist the access token to prevent an authentication request from being made on each page load. To enable this function, simply enable settings persistence prior to attempting a login. To maintain multiple auth tokens in storage, specify the prefix to use for storage/retrieval when enabling persistence. Otherwise, the prefix is optional and will default to purecloud.

const platformClient = require('purecloud-platform-client-v2');
var client = purecloud-platform-client-v2.ApiClient.instance;
client.setPersistSettings(true, 'optional_prefix');

Making Requests

All API requests return a Promise which resolves to the response body, otherwise it rejects with an error. After authenticating using one of the methods defined above, the following code will make an authenticated request:

Node.js

// Create API instance 
var authorizationApi = new platformClient.AuthorizationApi();
 
// Authenticate 
client.loginClientCredentialsGrant(clientId, clientSecret)
  .then(function() 
    // Make request to GET /api/v2/authorization/permissions 
    return authorizationApi.getAuthorizationPermissions();
  })
  .then(function(permissions) {
    // Handle successful result 
    console.log(permissions);
  })
  .catch(function(response) {
    // Handle failure response 
    console.log(`${response.status} - ${response.error.message}`);
    console.log(response.error);
  });

Web

// Create API instance 
var usersApi = new platformClient.UsersApi();
 
// Authenticate 
client.loginImplicitGrant(clientId, redirectUri)
  .then(function() {
    // Make request to GET /api/v2/users/me?expand=presence 
    return usersApi.getUsersMe({ 'expand': ["presence"] });
  })
  .then(function(userMe) {
    // Handle successful result 
    console.log(`Hello, ${userMe.name}!`);
  })
  .catch(function(response) {
    // Handle failure response 
    console.log(`${response.status} - ${response.error.message}`);
    console.log(response.error);
  });

Extended Responses

By default, the SDK will return only the response body as the result of an API function call. To retrieve additional information about the response, enable extended responses. This will return the extended response for all API function calls:

const platformClient = require('purecloud-platform-client-v2');
var client = purecloud-platform-client-v2.ApiClient.instance;
client.setReturnExtendedResponses(true);

Extended response object example (body and text have been truncated):

{
  "status": 200,
  "statusText": "",
  "headers": {
    "inin-ratelimit-allowed": "180",
    "inin-ratelimit-count": "3",
    "inin-ratelimit-reset": "3",
    "pragma": "no-cache",
    "inin-correlation-id": "ec35f2a8-289b-42d4-8893-c50eaf81a3c1",
    "content-type": "application/json",
    "cache-control": "no-cache, no-store, must-revalidate",
    "expires": "0"
  },
  "body": {},
  "text": "",
  "error": null
}

Error Responses

Error responses will always be thrown as an extended response object. Note that the error property will contain a JavaScript Error object.

Example error response object:

{
  "status": 404,
  "statusText": "",
  "headers": {
    "inin-ratelimit-allowed": "300",
    "inin-ratelimit-count": "6",
    "inin-ratelimit-reset": "38",
    "pragma": "no-cache",
    "inin-correlation-id": "d11bd3b3-ab7e-4fd4-9687-d04af9f30a63",
    "content-type": "application/json",
    "cache-control": "no-cache, no-store, must-revalidate",
    "expires": "0"
  },
  "body": {
    "status": 404,
    "code": "not.found",
    "message": "The requested operation failed with status 404",
    "contextId": "d11bd3b3-ab7e-4fd4-9687-d04af9f30a63",
    "details": [],
    "errors": []
  },
  "text": "{\"status\":404,\"code\":\"not.found\",\"message\":\"The requested operation failed with status 404\",\"contextId\":\"d11bd3b3-ab7e-4fd4-9687-d04af9f30a63\",\"details\":[],\"errors\":[]}",
  "error": {
    "original": null
  }
}

Debug Logging

There are hooks to trace requests and responses. To enable debug tracing, provide a log object. Optionally, specify a maximum number of lines. If specified, the response body trace will be truncated. If not specified, the entire response body will be traced out.

const platformClient = require('purecloud-platform-client-v2');
var client = purecloud-platform-client-v2.ApiClient.instance;
client.setDebugLog(console.log, 25);