How Genesis built multi-channel alerting using multiple RingCentral APIs
RingCentral provides several features which can and should be used to improve on-site safety. One of particular importance is Nomadic 911, which compels users to maintain accurate location records in RingCentral and therefore ensures emergency dispatch will arrive at the correct location.
In 2018 we at Genesis added support for RingCentral in our existing GenAlert On-Site Notifications solution. Initially, we reviewed API documentation (as we’d done previously when adding interoperability with our Call Reporting solution) to confirm there was a method we could use to detect 9–1–1 calls in real-time. Our goal at this point was simply to consume alerts when 9–1–1 was dialed, process these through our existing engine, and send out emails / SMS / Screen pop-ups as well as execute custom applications (trigger strobe lights, etc).
After getting an OAUTH2 token, we found this was easy enough to do by subscribing to the call events we wish to alert on. This required periodic renewal of subscriptions, retrieving a listing to confirm subscriptions are set up, etc., which are fairly self explanatory.
POST https://platform.devtest.ringcentral.com/restapi/v1.0/subscription
At this point we could have theoretically processed the call events and generated alerts, but it really wouldn’t have provided critical details (namely, location). We could send out an alert at this point, but we still don’t really know “who” called and “where” they are. We determined this wasn’t adequate yet.
We determined it was critical to collect details on the user who made the call: minimally, to be able to include the name of the person who made the call. So we leveraged the account-level extension API to retrieve a list.
GET https://platform.devtest.ringcentral.com/restapi/v1.0/account/accountId/extension
With this, we could determine the name attached to the phone. This definitely improved potential alerts, but still didn’t give us any indication of where that user was located. If it’s a physical, non-moving telephone then it could be manually added to our db and would not be an issue, but in practice this isn’t usually the case. We needed to programmatically retrieve the location information attached to the phone making the call, which required us to have the deviceID, and required us to make multiple subsequent API calls to get to the device-level information. This all had to be done in real-time once the alert was received to ensure location information accuracy.
Now that we know an emergency call was made, and the name + location of the caller, we need to get alerts to the people!
Emails and SMS alerting was already built-into our GenAlert solution, so we just leveraged the existing functionality without any need for significant modification. These alert paths are great in their reach — nearly everyone has access to email and can receive sms messages — but not as great for getting the desired immediate attention.
As a natural fit for most RingCentral users, we added Team Messaging support to allow us to leverage existing tools and post alerts to a Team. This required much of the same processes as with managing subscriptions, namely creating Teams, retrieving a list of configured Teams to validate the addition of each group (and to ensure no accidental duplicates), and posting messages to them with the alert details.
List configured Teams: GET https://platform.devtest.ringcentral.com/restapi/v1.0/glip/teams
Create a team: POST https://platform.devtest.ringcentral.com/restapi/v1.0/glip/teams
Create a post: POST https://developers.ringcentral.com/api-reference/Posts/createGlipPost
At this point alerts were being sent out 3 different ways, we were triggering custom hardware, and in totality the alerting was relatively difficult to miss. From discussion with users, the concern of real-time emergency validation was brought up, and additionally telephone-based alerting on security staff phones. Understandably, knowing that an emergency number was dialed is critically important, but knowing the nature of the emergency (and being able to identify misdials, for instance) is arguably as important.
To add telephone-based alerting and call validation, we needed to leverage the call supervision API. Doing this required using the information collected from previous API calls. This now allowed us to present the call audio to the security staff for validation.
The final step was to ensure all details of the call were recorded. Our background in call information recording, reporting and analytics already meant all the call details were being recorded, however we determined through discussions with RingCentral users that it was also important for them to retain copies of their emergency call audio. Complicating matters was the requirement to only record these calls, selectively, due to privacy concerns. We had to add on-demand call recording to selectively record only the necessary calls. Additionally, after the call completed we needed to retrieve the recording and send it to the appropriate group for archival.
Create call recording: POST https://platform.devtest.ringcentral.com/restapi/v1.0/account/accountId/telephony/sessions/telephonySessionId/parties/partyId/recordings
Download Call Recording: GET https://developers.ringcentral.com/api-reference/Call-Recordings/readCallRecording
Throughout the development, RingCentral Developer Support was routinely consulted with to better understand how the APIs worked, what we could and could not do, and any limitations & caveats which could potentially cause us issues in production. Many requested API changes or additions were also made which lessened overhead, and others made at the behest of customers wanting slightly different system behaviors.
