In this step-by-step tutorial, you are going to learn how to authenticate and access RingCentral platform services using Node JS. Click the "Start" button below to start the tutorial.
Start TutorialClone the project from GitHub and install the dotenv module.
If you don't know how to create a RingCentral app. Click here for instructions.
Copy the Client id and Client secret and add them to the .env-sandbox file.
RC_CLIENT_ID=
RC_CLIENT_SECRET=
Add the account login credentials to the .env-sandbox file.
RC_USERNAME=
RC_PASSWORD=
RC_EXTENSION=
If you want to specify variables for your production environment, repeat this step for the .env-production file.
Let's start by creating a file named ringcentral.js and import a few required libraries.
Read the ENVIRONMENT value from the .env file and load the .env-sandbox or .env-production accordingly.
For the sandbox environment, we save the data to the tokens_sb.txt.
For the production environment, we save the data to the tokens_pd.txt.
In your real application, you may want to keep the authentication data in a database. Or keep the file in a hidden place because it contains the access token and the refresh token!
To make this tutorial code reusable and extensible, we define the RingCentral class and implement a few utility functions.
authenticate()
get()
post()
Let's implement the authenticate() function to handle platform authentication.
1) Specify the endpoint, and the url variable by reading the platform server URL we defined in the configuration .env-[environment] file.
2) Specify the basic authorization string by joining the client Id with the client secret separated by a colon ":".
3/ Define the headers variable with the Content-Type, Accept and Authorization for the basic auth scheme.
4/ Define the body object with the grant_type, username and password. We encode the 'username' value for just in case if the username is an email address which has special characters.
5) Define the options object and specify values for the host, path, method and the headers.
1) Call the https.request and passing along the options object we created in the previous step.
2) Read the response and check the status_code. If the status_code is 200, load it into a JSON object jsonObj.
3) Define a tokensObj variable and assign the jsonObj to the "tokens" key/value pair. We also create the current timestamp and assign it to the "timestamp" key/value pair.
4) Save the tokensObj into a local file. I will discuss about how to use the file in the next step.
5) Return the jsonObj.access_token.
We can avoid posting an authentication request every time we need access to the platform by checking if the access_token is still valid.
To do that, we check the existence of the tokens_file file.
If the file exists, we read the file content and specify the expire_time variable by subtracting the tokensObj.timestamp from the current time. Then compare the expire_time with the access token expiration time tokensObj.tokens.expires_in.
If the expire_time is less than the access token expiration time, it means that the access token is still valid, so we return the tokensObj.tokens.access_token.
If the expire_time is greater than the access token expiration time, it means that the access token has expired. So we move on to compare the expire_time with the refresh token expiration time.
If the expire_time is less than the refresh token expiration time, it means that the refresh token is still valid so we can use it to request for a new access token. In this case, we redefine the body with the grant_type value is "refresh_token", and the refresh_token value is the actual refresh token read from the local file. Then we proceed to call the post request as discussed in the previous step.
If the tokens_file does not exist, we proceed the authentication as discussed in the previous step.
Now we implement the get() function to handle HTTP GET requests:
1) Call the authenticate() function to handle the authentication and get the access token.
2) Specify the url variable and assign the platform server URL we defined in the configuration .env-[environment] file.
3) Create a query string from the params and append it to the endpoint.
4) Define the headers variable with the "Accept" and "Authorization" key/value pairs with the "Authorization" scheme is "Bearer" followed by the access token.
5) Define the options object and specify values for the host, path, method and the headers.
6) Call the https.get function to send the request to RingCentral platform.
7) Read the response and check the status_code. If the status_code is 200, return the response.
Now we implement the post() function to handle HTTP POST requests
1) Call the authenticate() function to handle the authentication and get the access token.
2) Specify the url variable and assign the platform server URL we defined in the configuration .env-[environment] file.
3) Define the body variable and set the params as its value.
4) Define the headers variable with the "Content-Type", "Accept" and "Authorization" key/value pairs with the "Authorization" scheme is "Bearer" followed by the access token.
5) Define the options object and specify values for the host, path, method and the headers.
6) Call the https.request function to send the request to RingCentral platform.
7) Read the response and check the status_code. If the status_code is 200, return the response.
Now let's create a demo.js file and use the RingCentral class as shown in the demo code on the right-hand side.
In this demo, we implement 2 test functions:
get_account_extension():
We use the get function from the RingCentral class to get account extensions' information and print them out on the console.
send_sms():
We use the post function from the RingCentral class to send an SMS message to a recipientNumber and print the response out on the console.
$ node demo.js
You can further develop the RingCentral class to add PUT and DELETE methods as you wish.