This tutorial will show developers the basics of archiving your RingCentral Data using PHP. Click the 'Start' button below to begin.
Start TutorialData Archival provides developers the capability to store RingCentral Activity data via the API into their data persistence layer of choice, in this tutorial we will cover using PHP to offload RingCentral Activity data into either Amazon S3, or Dropbox.
It is critical for developers to know that RingCentral does not store RingCentral Activity data indefinitely. The RingCentral Data Retention Policy stores data differently depending upon:
Developers are highly encouraged to read the official RingCentral Data Retention Policy for the most current specifications and to understand how it impacts your data archival solution requirements.
We will be using a variety of RingCentral API Resources in this tutorial, and we wanted to list the primary API resources for your RingCentral Activity data:
Sometimes developers just need data from the UI for one-off reports, or to reconcile data during initial development. We will not use any of these data resources in this tutorial, but wanted to provide them for your reference to be thorough. Here is a list of non-API resources to access RingCentral Activity data:
Before you can follow along with this tutorial, you must have a web server with PHP installed with the appropriate version, dependencies, and modules/extensions as indicated in the README.md.
App Configuration Specs (minimum)
Please follow the directions in the Clone the Repository.
mv .env.example .env to rename the file .env.example to .env which is the environment variable file we use in this tutorial for local operation..env fileApplication KeyApplication SecretTo begin running this script, from the command line run $ php index.php.
Please read the README.md sections on Basic Usage to learn how to:
You can also see the demo code for these operations for further usage examples.
The index.php file contains code which contains references to each of the demos which actually perform the Basic Usage operations, let's take a look at how it is organized...
After defining this as a PHP file in line 1 with <?php opening tag, we give aliases to namespaces of the RingCentral PHP SDK.
We are leveraging Composer for dependency management in this demo application. We require these dependenicies using their namespace in a composer.json file.
As you can see the dependencies for operating this demo app are:
In production, you will likely have many more dependencies than are listed here.
A benefit of using Composer is the Autoload feature. To load the dependencies we have defined for this application in the composer.json file.
Next, we set the default timezone for this app to use UTC. We set this to UTC because that is the base timezone for RingCentral Call Log data (if not included as parameterized offsets).
Dotenv has become an invaluable tool for developers to load environment variables during local development. Here we instantiate Dotenv and tell it the .env file is located within the current working directory.
Then we call the load() method of the Dotenv instance to load the variables contained in the .env file we referenced previously.
Lastly, we cache some environment variables for simplified reference later use in this file.
This file, then requires the authData.php file located in the demo directory. Let's take a look and see what is happening here...
The beginning of authData.php defines this as a PHP file, defines error handling, references the RingCentral PHP SDK, and loads environment variables similar to what was done in the index.php file.
Beginning on line 14, we define a variable to hold a new instance of the RingCental PHP SDK, and provide it with the required parameters. Then, on line 16 we cache a reference to the RingCentral Platform object.
We will address storing and loading tokens from cache in the next step of the tutorial, but it is important to note that the catch portion (lines 49-59) of the try...catch is where we fetch a new access_token from the RingCentral API if we are unable to load the token from cache.
Lines 18-34 handle previous authentication values and loading them from cache if available.
The code sets the Platform Object's auth data to valid cached authentication data if possible, and if there is a token in cache, call the Platform Object's refresh() method to refresh the token ensuring we have a valid access_token.
Lines 30-36 of index.php use environment variables to determine if the code does/does not download call logs. For sake of the tutorial, we will assume $skipCallLog === false and has brought us into the demo/callLog.php file.
First some constants are configured as part of the delay logic used to long-poll all of the day's call logs.
Constants:
while loop in next stepNext in lines 30-33, a directory is created for local storage of these call logs.
Then the time range is configured in use o the dateFrom and dateTo parameters.
Lastly we create a placeholder array which will be used later for writing the call logs to a file.
After the code enters the while loop, has started the timer, and set dateTo and dateFrom parameters from environment variables, the variable $apiResponse is set to the result of the RingCentral Platform Object's get() method.
The first parameter for this is the path, in this case to call log /account/~/extension/~/call-log.
The second parameter is the array of query parameters we will use to filter. You can read the full list of GET Call Log Query Parameters in the RingCentral API Reference.
When the response is received we set the variable $apiResponseArray equal to the json() method's parsed value of the records. Note: the json() method is returned in each response using the RingCentral PHP SDK and simplifies parsing the data.
Lastly, we iterate the parsed call log records and push each record into the $callLogs array we defined earlier (used for writing the final file to disk).
After we receive each page of call log data in the response from the RingCentral API, we check to see if there are any additional pages of data remaining to be fetched.
If there are additional pages, we delay the next execution of the while loop and bump the $pageCount which is used in the query parameters for the next cycle's API request.
If there are no additional pages of call log records, we write the result to the console, write the JSON file to disk, set the $flag as FALSE, and then unset $callLogs so it is clear the next time this runs.
Lines 38-45 of index.php use environment variables to determine if the code does/does not download call recordings. For sake of the tutorial, we will assume $skipCallRecording === false and has brought us into the demo/callRecording.php file.
First some constants are setup for caching the recordingId, and defining directory and filenames we will use to store the data locally, and modifying the permission masks to make the directories and files writable.
Once the preparations have been completed, we iterate over the call log data to search for any call-log records which have a recording property.
If a call-log.record.recording exists, we then fetch the contentUri value for the recording, and use the RingCentral Platform Object's get() method to retrieve the binary asset which will be either .wav or .mp3 encoded audio.
Once the call recording download has been completed, write it to disk and store the call recording metadata in a .csv file.