Obtaining an Engage Access Token

Last updated: 2020-07-25 Contributors Craig ChanJohn WangPaco Vu
Edit this page

To access Engage Voice APIs, you need to create an Engage Voice App, and then with the client credentials, request an Engage Access Token. Once you have created an App, request a RingCentral Access Token and then using an Engage API to create an Engage Access Token. Then the Engage Access Token can be used to access Engage Voice APIs.

Note: Engage Voice APIs for Office customers are rooted at:

https://engage.ringcentral.com/voice/api/

Create an App

The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create Engage Voice App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create Engage Voice App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Give your app a name and description, then click Next.
  4. On the second page of the create app wizard enter the following:
    • Select 'Private' for Application Type.
    • Select 'Server-only (No UI)' for Platform Type.
  5. On the third page of the create app wizard, select the following permissions:
    • ReadAccounts
  6. We are using Password Flow authentication, so leave "OAuth Redirect URI" blank.

When you are done, you will be taken to the app's dashboard. Make note of the Client ID and Client Secret. We will be using those momentarily.

Retrieve RingCentral Access Token

Now retrieve a RingCentral access token using the following instructions:

RingCentral Authentication

Retrieve RingCentral Engage Access Token

Once you have a RingCentral Access Token, call the following Engage API to receive an Engage Bearer access token.

POST https://engage.ringcentral.com/api/auth/login/rc/accesstoken
Content-Type: application/x-www-form-urlencoded

rcAccessToken=<rcAccessToken>&rcTokenType=Bearer

Where:

  • <rcAccessToken> is the RingCentral Access Token you received from RingCentral Office authentication flow.
$ curl -XPOST https://engage.ringcentral.com/api/auth/login/rc/accesstoken \
      -d 'rcAccessToken=<rcAccessToken>' \
      -d 'rcTokenType=Bearer'
package main

import(
      "fmt"
      "encoding/json"
      "io/ioutil"
      "net/url"
    )

// EngageToken is an example and does not cover all the
// properties in the API response.
type EngageToken struct {
        AccessToken string `json:"accessToken"`
        TokenType   string `json:"tokenType"`
}

func RcToEvToken(rctoken string) (string, error) {
    res, err := http.PostForm(
            "https://engage.ringcentral.com/api/auth/login/rc/accesstoken",
            url.Values{"rcAccessToken": {rctoken}, "rcTokenType": {"Bearer"}})
    if err != nil {
            return "", err
    }
    if res.StatusCode >= 300 {
            return "", fmt.Errorf("Invalid Token Response [%v]", res.StatusCode)
    }
    engageToken := EngageToken{}
    bytes, err := ioutil.ReadAll(res.Body)
    if err != nil {
            return "", err
    }
    err = json.Unmarshal(bytes, &engageToken)
    return engageToken.AccessToken, err
}

func main() {
    rctoken := "myRcToken"

    evtoken, err := RcToEvToken(rctoken)
    if err != nil {
            log.Fatal(err)
    }
    fmt.Println(evtoken)
}
var https = require('https')

var RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN"

var url = "engage.ringcentral.com"
var path = '/api/auth/login/rc/accesstoken'
var body = 'rcAccessToken=' + RC_ACCESS_TOKEN + "&rcTokenType=Bearer"
var headers = { 'Content-Type': 'application/x-www-form-urlencoded' }

var options = {host: url, path: path, method: 'POST', headers: headers};
var post_req = https.request(options, function(res) {
      var response = ""
      res.on('data', function (chunk) {
          response += chunk
      }).on("end", function(){
          if (res.statusCode == 200){
              var tokensObj = JSON.parse(response)
              console.log(tokensObj.accessToken)
          }else{
              console.log(response)
          }
      });
    }).on('error', function (e) {
        console.log(e)
    })
post_req.write(body);
post_req.end();
import requests

RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN"
url = "https://engage.ringcentral.com/api/auth/login/rc/accesstoken"
body = "rcAccessToken=%s&rcTokenType=Bearer" % (RC_ACCESS_TOKEN)
headers = {
              'Content-Type': 'application/x-www-form-urlencoded'
          }
try:
    res = requests.post(url, headers=headers, data=body)
    if res.status_code == 200:
        jsonObj = json.loads(res._content)
        print (jsonObj['accessToken'])
    else:
        print (res._content)
except Exception as e:
    raise ValueError(e)
$RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN";

$url = "https://engage.ringcentral.com/api/auth/login/rc/accesstoken";
$body = 'rcAccessToken=' . $RC_ACCESS_TOKEN . "&rcTokenType=Bearer";
$headers = array ('Content-Type: application/x-www-form-urlencoded');

try{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($ch, CURLOPT_TIMEOUT, 600);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    $strResponse = curl_exec($ch);
    $curlErrno = curl_errno($ch);
    if ($curlErrno) {
        throw new \Exception($curlErrno);
    } else {
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($httpCode == 200) {
            $tokensObj = json_decode($strResponse);
            print ($tokensObj->accessToken);
        }else{
            print ($strResponse);
        }
    }
}catch (\Exception $e) {
    throw $e;
}

Response

The response will contain the accessToken property that can be used in an API call, as well as the refreshToken property that can be used to refresh the access token when the access token expires. Make sure to save both the accessToken and refreshToken for future API calls. Take note of the accountId property as that will be used to make future API calls.

The following is an abbreviated response.

{
  "refreshToken":"<rcEngageRefreshToken>",
  "accessToken":"<rcEngageAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"john.wang@example.com",
      "username":"john.wang@example.com",
      "agentType":"AGENT",
      "rcUserId":222222,
      "accountId":"333333",
      "accountName":"RingForce",
      "agentGroupId":null,
      "allowLoginControl":true,
      "allowLoginUpdates":true
    }
  ],
  "adminId":1111,
  "adminUrl":"/voice/admin/",
  "agentUrl":"/voice/agent/",
  "ssoLogin":true
}

Example Engage Voice API Call

The following is an example Engage Voice API Call using a RingCentral Engage Access Token.

GET https://engage.ringcentral.com/voice/api/v1/admin/users
Authorization: Bearer <rcEngageAccessToken>

Refresh RingCentral Engage Access Token

The RingCentral Engage Access Token will only live for a few minutes (currently 5 minutes) before needing to be refreshed. If the access token is expired, the API request will respond with:

401 Unauthorized

Jwt is expired

Use the refreshToken to refresh the RingCentral Engage access token, by calling the following Engage API.

POST https://engage.ringcentral.com/api/auth/token/refresh
Content-Type: application/x-www-form-urlencoded

refresh_token=<rcEngageRefreshToken>&rcTokenType=Bearer

Where:

  • <rcEngageRefreshToken> is the RingCentral Refresh Token you received from RingCentral Engage authentication flow.

Response

The response will contain the same accessToken property that can be used in an API call, but the refreshToken property will be a new refresh token that can be used to refresh the access token when the access token expires. Make sure to save the new refreshToken for future refresh token API calls.

The following is an abbreviated response.

{
  "refreshToken":"<rcEngageRefreshToken>", //Save this as it will be new.
  "accessToken":"<rcEngageAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"john.wang@example.com",
      "username":"john.wang@example.com",
      "agentType":"AGENT",
      "rcUserId":222222,
      "accountId":"333333",
      "accountName":"RingForce",
      "agentGroupId":null,
      "allowLoginControl":true,
      "allowLoginUpdates":true
    }
  ],
  "adminId":1111,
  "adminUrl":"/voice/admin/",
  "agentUrl":"/voice/agent/",
  "ssoLogin":true
}