In this step-by-step tutorial, you are going to learn how to authenticate and access RingCentral platform services using Python native API. Click the "Start" button below to start the tutorial.
Start TutorialClone the project from GitHub and install the dotenv module.
If you don't know how to create a RingCentral app. Click here for instructions.
Copy the Client id and Client secret and add them to the .env-sandbox file.
RC_CLIENT_ID=
RC_CLIENT_SECRET=
Add the account login credentials to the .env-sandbox file.
RC_USERNAME=
RC_PASSWORD=
RC_EXTENSION=
If you want to specify variables for your production environment, repeat this step for the .env-production file.
Let's get started by creating a file named ringcentral.py and import a few required libraries.
We read the ENVIRONMENT value from the .env file and load the .env-sandbox or .env-production accordingly.
For the sandbox environment, we save the data to the tokens_sb.txt.
For the production environment, we save the data to the tokens_pd.txt.
In your real application, you may want to keep the authentication data in a database. Or keep the file in a hidden place because it contains the access token and the refresh token!
To make this tutorial code reusable and extensible, we define the RingCentral class and implement a few utility functions.
authenticate()
get()
post()
Let's implement the authenticate() function to handle platform authentication.
1) Specify the url variable by adding the /restapi/oauth/token endpoint to the platform server URL we defined in the configuration .env-[environment] file.
2) Specify the basic authorization string by joining the client Id with the client secret separated by a colon ":".
3) Define the headers variable with the Content-Type, Accept and Authorization for the basic auth scheme.
4) Define the body object with the grant_type, username and password. We encode the body for just in the case the username is an email address which has special characters.
1) Use the requests.post function to call the authentication endpoint, passing along the headers and the body of the post request.
2) Check the response status_code. If the status_code is 200, we read the response and load it into a JSON object jsonObj.
3) Define a tokensObj variable and assign the jsonObj to the "tokens" key/value pair. We also create the current timestamp and assign it to the "timestamp" key/value pair.
4) Save the tokensObj into a local file. I will discuss about how to use the file in the next step.
5) Extract the access_token from the jsonObj and keep the token in the class self.access_token variable.
We can avoid posting an authentication request every time we need access to the platform by checking if the access_token is still valid.
To do that, we check the existence of the tokens_file file.
If the file exists, we read the file content and specify the expire_time variable by subtracting the tokensObj['timestamp'] from the current time. Then compare the expire_time with the access token expiration time tokenObj['tokens']['expires_in'].
If the expire_time is less than the access token expiration time, it means that the access token is still valid, so we save the tokenObj['tokens']['access_token'] to the class self.access_token.
If the expire_time is greater than the access token expiration time, it means that the access token has expired. So we move on to compare the expire_time with the refresh token expiration time.
If the expire_time is less than the refresh token expiration time tokenObj['tokens']['refresh_token_expires_in'], it means that the refresh token is still valid so we can use it to request for a new access token. In this case, we redefine the body with the grant_type value is "refresh_token", and the refresh_token value is the actual refresh token read from the local file. Then we proceed to call the post request as discussed in the previous step.
If the tokens_file does not exist, we proceed the authentication as discussed in the previous step.
Now we implement the get() function to handle HTTP GET requests:
1) Call the authenticate() function to handle the authentication and get the access token.
2) Specify the url variable by adding the endpoint to the platform server URL we defined in the configuration .env-[environment] file.
3) Parse the params and complete the url with query parameters.
4) Define the headers variable with the "Accept" and "Authorization" key/value pairs with the "Authorization" scheme is "Bearer" followed by the access token.
5) Call the requests.get function to send the request to RingCentral platform.
6) Check the response.status_code. If the status_code is 200, return the response.
Now we implement the post() function to handle HTTP POST requests:
1) Call the authenticate() function to handle the authentication and get the access token.
2) Specify the url variable by adding the endpoint to the platform server URL we defined in the configuration .env-[environment] file.
3) Define the body variable and set the params as its value.
4) Define the headers variable with the "Content-Type", "Accept" and "Authorization" key/value pairs with the "Authorization" scheme is "Bearer" followed by the access token.
5) Call the requests.post function to send the request to RingCentral platform.
6) Check the response.status_code. If the status_code is 200, return the response.
Now let's create a file demo.py and use the RingCentral class as shown in the demo code on the right-hand side.
In this demo, we implement 2 test functions:
get_account_extension():
We use the get function from the RingCentral class to get account extensions' information and print them out on the console.
send_sms():
We use the post function from the RingCentral class to send an SMS message to a recipientNumber and print the response out on the console.
$ python demo.py
You can further develop the RingCentral class to add PUT and DELETE methods as you wish.