Use cURL to access RingCentral Platform API

cURL is a computer software project providing a library and command-line tool for transferring data using various protocols. It’s one of my favorite command utilities.

Lots of programmers, including me, like to make quick HTTP requests using cURL. It’s super convenient because you don’t need to write any code.

RingCentral provides RESTful APIs for most of its services. You can do almost anything with RESTful API that you can do with RingCentral apps, including but not limited to: send SMS/MMS/Fax, make RingOut calls, access your address-book, access data and send messages on RingCentral Glip, etc.

In this article I am going to give you some examples on how to use cURL to access RingCentral Platform API. I would like to divide the content into three parts:

• Firstly, how to get access token
• Secondly, how to make normal API requests
• Lastly, how to make multipart API requests

Get access token

First and foremost, register a free RingCentral developer account if you don’t have one.

Then create a RingCentral app in RingCentral developer console:

Make sure the app you created supports Password flow, because we will use password flow for the following tutorial:

For permissions, please at least select SMS and Fax, we will need them later:

After the app is created, please find the section below:

In the image above, you can find the credentials that we can use later. Please note that , we will use Account as username later.

OK, it’s time for cCUL to show up, here is the command to get access token:

curl -i -X POST 'https://platform.devtest.ringcentral.com/restapi/oauth/token' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u '<clientId>:<clientSecret>' \
-d 'username=<username>&password=<password>&extension=&grant_type=password'

Please note that, parameters inside <…> are what you should replace with real values. All of the values could be find from the app we just created.

Sample output:

Bingo! Now you got the access token!

Make normal API requests

Most of RingCentral APIs accepts Content-Type application/json, we call such API requests normal API requests. Let’s take SMS sending and reading for example:

SMS Sending:

curl -i -X POST "https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/sms" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{ "to": [{ "phoneNumber": <to_number> }], "from": { "phoneNumber": <from_number> }, "text": "Hello world!" }'

Again, parameters inside <…> are what you should replace with real values.

Sample output:

In the output, there is an id property, we will use this property to issue a SMS read request:

curl -i "https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/message-store/<message_id>" \
-H "Authorization: Bearer <access_token>"

Don’t forget to replace parameters inside <…> with real values.

Sample output:

The output is almost the same as the last one. However messageStatus changed from Queued to Delivered. It is because SMS might take from seconds to minutes to deliver.

OK, now you can both send SMS and read SMS with cURL. In theory, you are able to invoke 80% of RingCentral’s API calls. Because most of them are just HTTP GET like SMS Reading or HTTP POST like SMS sending.

Let’s try something harder, sending a file to RingCentral server!

Make multipart API requests

Sometimes you need to send files to RingCentral servers, for example, sending fax, updating your profile image, uploading custom greeting audio…etc. Let’s take fax sending for example:

curl -i "https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/fax" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token>" \
-F "request=@request.json;type=application/json" \
-F "attachment=@hello.txt;type=text/plain"

Again, parameters inside <…> are what you should replace with real values.

Content of request.json file:

{
 "to": [{ "phoneNumber": <fax_receiver> }]
}

Content of hello.txt:
<Whatever text you want to send.>

Sample output:

You can also send pdf:
-F “attachment=@test.pdf;type=application/pdf”

Or send image:
-F “attachment=@test.png;type=image/png”

The notable thing is the -F argument. It is used to create multipart/form-data: -F, — form CONTENT Specify HTTP multipart POST data (H)

OK, now you know how to send files to RingCentral API server, cheers! 🍻

Sample for sending MMS

curl -i 'https://platform.devtest.ringcentral.com/restapi/v1.0/account/~/extension/~/sms' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access_token>' \
-F 'request=@request.json;type=application/json' \
-F 'attachment=@test.png;type=image/png'

Sample request.json file:

{ "to": [{ "phoneNumber": 1234567890 }], "from": { "phoneNumber": 1234567890 }, "text": "Hello world!" }

Here is the MMS received on my mobile phone:

Summary

In this article, we went through together the process to create a RingCentral app which supports password flow, get an access token, send normal API requests and send files to RingCentral API server.

Now you should have enough knowledge to invoke RingCentral platform API with cURL, right in the command line!

That’s all, thank you! Please leave comments or chat with us live in our 💬RingCentral Glip Developers Public Group 💬.