Welcome to the tutorial

This tutorial shows how to use RingCentral Company Presence Event Push Notification API to get notified when a new call recording is logged into a user call log database.

Requirements

You must have a RingCentral developer account. If you don't have one, click here to create a free developer account.

You also have to create a RingCentral app with the "ReadCallLog" and "ReadPresence" permissions. And retrieve your app ClientId and ClientSecret for using with this tutorial. Choose "Server-only (No UI)" for the app's platform type and "Password flow" for the Authorization flows.

Clone the project from GitHub

Run the commands shown on the right-hand side to clone the project from GitHub

Navigate to the folder and install the dependencies

Set environment parameters

Rename the dotenv to .env and provide your app credentials, RingCentral sandbox account's username and password.

Note: If you want to run the app on your production environment, make sure that your app is graduated and use the app production clientId and clientSecret. Also remember to change the MODE=production.

Instantiate the RingCentral Node JS SDK

First, we create the SDK instance rcsdk and initialize it with the clientId and clientSecret.

Then we call the rcsdk.platform() function to get the platform instance. The platform instance will be used later to login and call RingCentral APIs.

We also call the rcsdk.createSubscription() function to create a subscription instance and implement a callback function 'presenceEvent' to receive notification events.

Login to RingCentral account

To login RingCentral account, we call the platform.login() function with the given account's username and password.

Note: In this application, we will use the push notification for company presence events. This means that we need to login with the main company username or with a user who has the admin role, so that we can receive push notification event for all users under the company account..

Implement notification subscription

After logged in successfully, we are ready to subscribe for push notification so that we can receive company presence events.

Create notification subscription

Before creating a new subscription for notification, we may need to detect if we have created one earlier. This step is necessary because the app could be terminated and rerun for any reason and we don't want to create multiple subscriptions.

When a push notification subscription is registered successfully, we will receive a response with the subscriptionId. We will save the subscriptionId locally (in this project we save it in the subscriptionId.txt file) so that we can use it to delete that subscription before creating a new one.

When we run the app for the first time, we don't have the subscriptionId (or the file does not exists), we will call the subscribeForNotification() function, where we will register for a new subscription.

When we rerun the app, we read the subscriptionId from the local file, then we will call the removeRegisteredSubscription(id) function with the subscription Id to delete that subscription before creating a new one.

Subscribe for notifications

RingCentral push notification supports multiple events notification. This means that we can subscribe for notifications of several different events such as when there is an incoming SMS, when a SMS message is deleted, when there is an incoming call etc. in a single subscription.

In this particular app, we are only interested at company presence events. Thus, we subscribe for just one event type of presence.

After registered successfully, we parse the response to get the subscription Id and save it to the local "subscriptionId.txt" file.

Now we are ready to receive company presence events.

Capture the event information

Whenever we receive a company presence event, we capture the extensionId and the telephonyStatus and create an empty startTime then add those parameters to a user object then call the checkTelephonyStatusChange(user) function, passing the user object along.

Manage the list of users under the company account

Inside the checkTelephonyStatusChange(user) function, we checked if the extensionId has been added to the usersList.

If the extension is not found from the list, we add the new user object to the usersList. We also check if the telephonyStatus is 'Ringing' then we create a timestamp to specify the startTime.

Detect the telephony status changed sequences

The Account Presence Event provides us with different user statuses. In this application, we are interested at only the telephonyStatus which has the following value:

'NoCall' | 'CallConnected' | 'Ringing' | 'OnHold' | 'ParkedCall'

When an extension (a user) under an account has no active call, its telephonyStatus is ‘NoCall’. When there is an incoming or outgoing call on an extension, the telephonyStatus is changed from ‘NoCall’ to ‘Ringing’.

Now, if the incoming/outgoing call is accepted, the telephonyStatus is again changed from ‘Ringing’ to ‘CallConnected’.

Then if the call is terminated, the telephonyStatus will be changed from ‘CallConnected’ to ‘NoCall’.

Build the logics

First of all, we need to detect the time when the call started ringing. That is whenever the telephonyStatus is changed from 'NoCall' to 'Ringing', we create the timestamp and keep it in the startTime in a user object. The startTime value will be used to define the time range when we read the user call logs.

Then we detect if the telephonyStatus is changed again from 'Ringing' to 'CallConnected' to define if the user is having an active call.

Finally, all we need is to wait for an active call terminates. That is when the telephonyStatus is changed from 'CallConnected' to 'NoCall'.

After the call is terminated, we create the timestamp for the stopTime, and we wait for about 20 seconds for the system to update the call log database, then proceed to read the call-log.

Read the call log

We use the extensionId to create an endpoint for reading the call log of that particular extension.

We use the startTime for the dateFrom parameter and the stopTime for the dateTo parameter to fetch call log information within that period of time. It is the period of time between the call started ringing and the call is terminated.

We also set the query parameter recordingType='All' to avoid reading the call log item without call recording.

Detect call recording

We parse the response and check the records array to find a recording object.

In this tutorial, if there is a new call recording, we will call the saveAudioFile(record) function to save the recording binary file to a local folder recordings. But it's up to you now to use the event of a new call recording for your real application.