Take Control of Your Data using RingCentral APIs

In today’s day and age data is the most vital asset for any organization and with all the policy, regulation and compliance requirements around data (example GDPR) taking complete control of your data is a must. We at RingCentral make every effort to make sure our platform provides our customers complete control of their data. Our customers have also increasingly asked us for account-level retention and deletion capabilities. These are the reasons we are introducing a number of API enhancements to enable you to take control of your RingCentral data.

The API enhancements we are introducing in release 10.2:

1. Delete Messages APIs (Admin on behalf of other)
2. Account Call-Log Sync API ExtensionId enhancement

Upcoming enhancements include:

1. Account Message Store Report API
2. Data Retention Policy API

Delete Messages APIs (Admin On Behalf of Others)

With this enhancement, administrator accounts (typically in the form of a service account) now have the ability to delete user messages on their behalf. This can be by messageId or via a filter using messageType and dateTo.

Use Cases

• Data Retention: As a company you want more control on your data retention by only storing data for certain extensions or certain message types and deleting anything else. This will enable you to do just that by passing message type and dateTo query parameters. Also this allows the admin to manage the data on behalf of other users.
• GDPR (General Data Protection Regulation): As a compliance requirement, your EU user wants all his SMS data for his extension to be deleted, this API allows your App to take care of it on behalf of the user.

There are two APIs that support this:

Delete Message by Id

The Delete Message By Id API has a single required path parameter, the messageId.

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

Delete Messages by Filter

The Delete Messages by Filter API has two optional query parameters, dateTo and messageType.

DELETE /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store?dateTo=2018-07-01T00:00:00Z&messageType=SMS

• dateTo: Messages received till that date will be deleted in RFC-3339 format. If this is not supplied, all messages will be deleted.
• messageType: The message type to be deleted, e.g. Fax, SMS, Voicemail, Pager, Text, All. All is the default value

A successful response returns a 204 No Content response.

Delete Messages on Behalf of other users

Account Call-Log Sync API ExtensionId enhancement

In 10.2, we also added extensionId in the response for the accountcall-log-sync API in detailed view mode described in the Developer Guide:

http://ringcentral-api-docs.readthedocs.io/en/latest/calllog_sync/

This will enable you to get the extensionId’s from your call log record in a single call and enable you to associate the messages to users and take appropriate actions on those extensions based on your business workflow.

Use Cases

• Data Compliance: In order to comply with regulatory requirements of FINRA and FRCP, you need to read all recent message data for all your employees and associate the message to a user extension. The call-log sync detailed view will allow you to achieve that seamlessly in a single API call.

Account Call Log Sync API

Use the standard call-log-sync API as follows.

GET /restapi/v1.0/account/~/call-log-sync?&syncType=FSync&view=Detailed&recordCount=5

The response will now include an extension property as follows:

{
    "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/147043006/call-log-sync?syncType=FSync&recordCount=5",
    "records": [
        {
            "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/147043006/call-log/PAIEalSxZVVNQA?view=Detailed",
            "id": "PAIEalSxZVVNQA",
            "sessionId": "2833792006",
            "startTime": "2018-08-14T19:02:53.820Z",
            "duration": 9,
            "type": "Voice",
            "direction": "Outbound",
            "action": "RingOut PC",
            "result": "Wrong Number",
            "to": {
                "phoneNumber": "+16197619503",
                "location": "Chula Vista, CA"
            },
            "from": {
                "phoneNumber": "+17204960664",
                "name": "Something 1 New 1"
            },
            "extension": {
                "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/147043006/extension/147043006",
                "id": 147043006
            },
            "transport": "PSTN",
            "lastModifiedTime": "2018-08-14T19:03:08.002Z",
            "billing": {
                "costIncluded": 0,
                "costPurchased": 0
            },
            "legs": [
                {
                    "startTime": "2018-08-14T19:02:53.820Z",
                    "duration": 9,
                    "type": "Voice",
                    "direction": "Outbound",
                    "action": "RingOut PC",
                    "result": "Wrong Number",
                    "to": {
                        "phoneNumber": "+16197619503",
                        "location": "Chula Vista, CA"
                    },
                    "from": {
                        "phoneNumber": "+17204960664",
                        "name": "Something 1 New 1"
                    },
                    "extension": {
                        "uri": "https://platform.devtest.ringcentral.com/restapi/v1.0/account/147043006/extension/147043006",
                        "id": 147043006
                    },
                    "transport": "PSTN",
                    "legType": "RingOutClientToSubscriber",
                    "master": true
                }
            ]
        }
    ],
    "syncInfo": {
        "syncType": "FSync",
        "syncToken": "GQMAAAFlDm3mAAQAAAFlOjX0TwgAAAAACMOyvg0AAAAAqOg8Bg4AAAFlDm3mABEADwAxADUAMwAzADUANAA1ADQAMAA4ADAAMAAwAF8AMBIAAAFlOjX0UhQBFQAYABoC9QcCDA",
        "syncTime": "2018-08-14T20:52:19.165Z"
    }
}

Account Message Store Report APIs

We introduced this new API that allows you to get a list of all message-store data with and without attachments. This is an asynchronous call, which provides you with an internally generated report id for the report and you can query that report id for completion status. Once the report is completed , you can query the report id to get the content URI for all your messages with and without attachment.

Use Cases

• eDiscovery: There is a litigation involving your specific departments and you need to track all the messages for those departments and associate them to the users and finally save back them to a system where you can put a legal hold. You can use this API to get a list of all the messages that has been generated in your system, with and without attachment and track them by users.

For this API, your app will need the ReadMessages user permission and Users app permission.

Create Data Collecting Task API

The data collecting task API creates a new archive.

POST /restapi/v1.0/account/{accountId}/message-store-report

• Application Permission: Users
• User Permission: ReadMessages
• Query parameters: dateFrom and dateTo in RFC-3339 format

Example Request

POST /restapi/v1.0/account/~/message-store-report
{
  "dateFrom": "2015-11-18T14:28:53.000Z"
}

Example Response

HTTP 200 OK

{
    "id" : "402297343008-402297343008-f674e48cbb5a479bac124ca8afcffb3d",
    "uri" : "https://platform.ringcentral.com/restapi/v1.0/account/402297343008/message-store-report/402297343008-402297343008-f674e48cbb5a479bac124ca8afcffb3d",
    "status" : "Accepted",
    "accountId": "402297343008",
    "extensionId": "402297343008",
    "creationTime" : "2018-04-20T13:30:09Z",
    "lastModifiedTime" : "2018-04-20T13:30:09Z",
    "dateFrom": "2015-11-18T14:28:53.000Z",
    "dateTo": "2018-04-20T13:30:09Z"
}

Check Report Status API

GET /restapi/v1.0/async-task/<taskid>

Example Response — In Progress

{
  "id" : "147043006-147043006-5b3109afbd06443b840167d0808d8b4f",
  "uri" : "https://platform.ringcentral.com/restapi/v1.0/async-task/147043006-147043006-5b3109afbd06443b840167d0808d8b4f",
  "status" : "InProgress",
  "creationTime" : "2018-04-20T13:30:09Z",
  "lastModifiedTime" : "2017-10-12T17:19:15Z"
}

Example Response — Completed

{
  "id" : "147043006-147043006-5b3109afbd06443b840167d0808d8b4f",
  "uri" : "https://platform.ringcentral.com/restapi/v1.0/async-task/147043006-147043006-5b3109afbd06443b840167d0808d8b4f",
  "status" : "Completed",
  "creationTime" : "2018-04-20T13:30:09Z",
  "lastModifiedTime" : "2017-10-12T17:20:23Z",
  "result": {
    "uri": "https://platform.ringcentral.com/restapi/v1.0/account/402297343008/message-store-report/147043006-147043006-5b3109afbd06443b840167d0808d8b4f/archive"
  }
}

Retrieving Report API

Once the report archive is ready, you can download it with and without attachments:

GET /account/{accountId}/message-store-report/{reportId}/archive

An example response is as follows:

{
  "records": [ { 
    "size": 106107,
    "uri": "https://platform.ringcentral.com/restapi/v1.0/account/402297343008/message-store-report/NDAyMjk3MzQzMDA4fDIwMTUtMTEtMThUMTQ6Mjg6NTMuMDAwWnwyMDE4LTA0LTIwVDEzOjMwOjA5Wg==/402297343008/archive/0"
   }, {
    "size": 73708885,
    "uri": "https://platform.ringcentral.com/restapi/v1.0/account/402297343008/message-store-report/NDAyMjk3MzQzMDA4fDIwMTUtMTEtMThUMTQ6Mjg6NTMuMDAwWnwyMDE4LTA0LTIwVDEzOjMwOjA5Wg==/402297343008/archive/1"
   } ]
}

The archive URI is specified in the uri property and the file will contain the folder structure below:

/account
  /{account.id} //real account ID
    /extension/
      /{extension1.id} //real extension ID
        /message-store
          /{message11.id} //real message ID
            /content
          ...
          /{message1M.id} //real message ID
            /content
      ...
      /{extensionN.id} //real extension ID

Without Attachments

GET /account/{accountId}/message-store-report/{reportId}/archive/0

The archive will contain the folder structure below:

/account
  /{account.id} //real account ID
    /extension/
      /{extension1.id} //real extension ID
      ...
      /{extensionN.id} //real extension ID

each extensionX.id folder contains a JSON file message-store.json.

Data Retention Policy API (Coming Soon)

This is an API to set Custom Data Retention Policy. We will be introducing an API to manage your message store data retention policy. By default RingCentral stores 90 days of message store data (SMS, MMS, VoiceMail, Fax, and Pager) or 10K messages. Some of our customers wanted more control on the data retention policy and wanted an API to configure it. With this API you can just do that.

Use Cases

• Data Volume Management : As a company you are generating huge volumes of data and want to ensure you only keep 60 days worth of data and not more. This API allows you to exactly do that, i,e configure a custom data retention policy for less than 90 days

Note: As a company policy if you want to configure data retention more than 90 days, then you should contact RingCentral professional services.

Get Message Store Configuration API

GET /restapi/v1.0/account/{accountId}/message-store-configuration

• Application Permission: EditAccounts
• User Permission: AccountAdministration
• Access Level: Advanced

Update Message Store Configuration API

The Update Message Store Configuration API allows you to set a custom retention period in days from 7 to 90 days.

PUT /restapi/v1.0/account/{accountId}/message-store-configuration
{
  "retentionPeriod": 30
}

You will receive a 200 OK response as follows:

HTTP 200 OK

{
  "retentionPeriod": 30
}

Next Steps

Hope this article was useful to you and you can start using the APIs and provide us more feedback for improvement.

If you have not yet signed up for the developer program please do by clicking on https://developer.ringcentral.com/. Looking forward to your questions and comments.