Data Archival of your RingCentral account activity is a critical skill all RingCentral Developers should have and maintain.

Data Archival provides the capability to store your Ring Central Activity via the RingCentral API to enable rich integrations and to extend the persistent availability of your data beyond the Data Retention Policy defined by Ring Central.

The following data is most commonly archived by developers:

  • Call Log Data (meta-data about call activity generated by your RingCentral account users)
  • Call Recording and Call Recording Metadata (the description and associated binary audio files created when a call is recorded)
  • Message Store Data
    • Fax Attachments
    • SMS Messages
    • Voice mail binary audio files

Developers typically archive their data into persistent storage solutions such as:

  • RDBMS (MySql, MSSQL, etc...)
  • NoSQL (MongoDB, CouchDB, etc...)
  • Big Data (Hadoop, etc...)
  • 3rd Party Data Storage Services (Amazon S3, Dropbox, etc...)

NOTE: Developers will need to determine their own persistent solution needs based upon their unique storage requirements

Your business communication data is created when users make and receive phone calls, text messages, voice mail, and faxes using your Ring Central account. This data may have important immediate or future value for your organization. It may come as a surprise, but Ring Central does NOT store your business communication data indefinitely. If businesses wish to perform historical analysis, or maintain their business communication data, your organization will need to implement a data archival solution.

Ring Central Online Account Portal does provide users with the tools to export some of this data, but it is time consuming and prone to human error if not done correctly. This is why we consider Data Archival a best practice for all of our customers.

Data Archival APIs

There are several routes developers will need to use depending upon the type of data you need to archive.

The base route for accessing call log data is scoped to the Account Level or the Extension Level depending upon the role of the authenticated access_token user.

Call Log, Recording Meta Data, Recording (binary audio files)

Account-Level Call Log data

This is data for the entire account. Please note that call recording meta data and the binary audio files which are call recordings are only accessible at the account level.

  • /restapi/v1.0/account/{accountId}/call-log
  • /restapi/v1.0/account/{accountId}/call-log/{callRecordId}
  • /restapi/v1.0/account/{accountId}/recording/{recordingId}
  • /restapi/v1.0/account/{accountId}/recording/{recordingId}/content

Extension-Level Call Log data (this is data for only a specific extension within your RingCentral account).

  • /restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log
  • /restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log/{callRecordId}

Message Store Data

The Message Store API enables developers to send Fax, Pager, and SMS messages. The Message Store API also exposes development resources for retrieving data to archive, and to delete that data from RingCentral.

Developers will need to obtain the list of messages from an extension mailbox first (unless you already have a specific messageId on-hand): See the API Reference for complete information about the various query parameters which can be used to filter the data returned in the list.

  • /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store

Then iterate the records returned from the message-store list to return individual message record(s) by the given message ID(s). The length of inbound messages is unlimited and batch requests are supported.

  • /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}

Optionally, developers may then choose to have attachment data (sent as a media stream) returned about a particular message by using the attachmentId of a specific message record.

  • /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}/content/{attachmentId}

Data Archival API Permissions

There are various API Permissions applications must be granted depending upon the type data developers need to archive from the RingCentral API:

Account level Call Log Records, and Extension level Call Log Records require the ReadCallLog API permission

  • Call Recording Metadata and Call Recording Content require the ReadCallRecording API Permission
  • Message Store Data (List, Message, Attachment) all require the ReadMessages API Permission

API Groups and Rate Limits

In a standard basic usage plan, Heavy API Group rate limits to: 10 requests / 60 seconds. In a standard basic usage plan, Medium API Group rate limits to: 40 requests / 60 seconds. In a standard basic usage plan, Light API Group rate limits to: 50 requests / 60 seconds.

Call Log API Groups are all Heavy

Message Store API Groups:

  • Get Message List: Light
  • Get Message by ID: Light
  • Get Message Attachment: Medium

Read API Developer Guide - API Rate Limits to understand the rate limits for the Usage Plan assigned to your organization, and the limitations code must address.

Non-Progammatic Ways to Access Data used in Archival

Frequently, while developing an application or integration, it is helpful for Developers to be able to test or invalidate data or reconcile their programmatic data against an official record. The training content contained in this document describes how Developers can use the RingCentral API to access and view your account activity data. You can use one of the following methods to access this data as well:

Ring Central Users can view their voicemail, fax messages, and call logs through the Ring Central Online Account Portal, Ring Central desktop app and Ring Central mobile app. Text Messages can be viewed through the Ring Central desktop app and mobile app. Here is a list of official Ring Central knowledge base articles describing the manual processes and tools available for gathering your Activity Log data.

Now we will take a moment to review the Ring Central Data Retention Policy further since it highlights important information as it relates to your Data Archival system architecture.

Call Log Data Retention Policies

The standard RingCentral Message Store and Account Data Retention Policy dictates the quantity or length of time call log records and call recordings are stored by RingCentral, this is known as the RingCentral Data Retention policy, and it:

  • Enforces rules for managing account data storage
  • Provides specifications for development considerations with data archival
  • Has different rules for HIPAA and non-HIPAA RingCentral Accounts

To see the most up-to-date version of this policy please read the following article in the RingCentral Knowledge Base:

http://success.ringcentral.com/articles/en_US/RC_Knowledge_Article/2178

We recommend bookmarking the above URL for your reference.

Common Use Cases

The primary use case developers have for data archival is to prevent data-loss caused by the RingCentral Data Retention Policy.

Other common use cases are:

  • Volume usage invalidation and account usage reconciliation
  • Analytics and Reporting
  • Legal Data Storage Requirements (such as SEC requirements for stock traders)
  • Business Process Improvements and Training
  • Call Sentiment Analysis and Predictive Analytics

Example

Data Loss Prevention is the most common use case, but what does that look like exactly?

Assuming the following:

  1. Your business has a non-HIPAA RingCentral Account
  2. Automatic Call Recordings are enabled on all extensions
  3. There are 4000 users receiving 10 calls each daily on average
  4. Your organization requires all call recording data to be accessible at any time

The issue is: 4,000 users X 10 calls daily = 40,000 call recordings daily Multiplied by 30 days = 1,200,000 call recordings monthly * RingCentral begins truncating call recordings at 90 days or 100,000 recordings in your acocunt (it drops oldest recording files based on these fixed limits)

In this example, a developer would need to implement a data archival solution.

RingCentral Archiver

RingCentral Customers needing a turn-key solution and whom are using Dropbox can use the Ring Central Archiver available in the App Gallery using the URL below. It is supported by Ring Central and backs up your data as soon as you have it installed.

  • Available in the RingCentral App Gallery
  • Backs up all your important business communication data from RingCentral
  • Moves data to Dropbox hourly over SSL

Developer Sample Application

Additionally, there is the Call Recording Download Sample application available on Github.

This is not an officially supported tool, but can serve as a handy starting point for developers building data archiving solutions with Amazon S3, local server solutions, or on DropBox. It can be easily customized and pull requests with improvements are always welcomed.

  • Available on Github (MIT license)
  • Requires:
    • PHP 5.3.29+
    • Composer
    • cURL Extension support in PHP
  • URL: https://github.com/anilkumarbp/Sample-Demo-to-Download-Call-Recordings
  • Downloads Call Logs and/or Recordings to:
    • Local File System
    • Amazon S3 Bucket (requires Amazon account)
    • Save Call Recordings to DropBox (requires DropBox account)
  • Uses the official RingCentral PHP SDK

Developers who choose to build their own solutions (or use this sample application), will need to define an application in the Ring Central Developer Portal. Use the settings listed in this page for your application. The resulting application will be able to download all your Ring Central activity data within your account when used with administrative authentication credentials.

Developers can adjust the Permissions needed if requirements dictate only specific types of business communication data needs to be backed up.