Template for calling Ring Central APIs with PHP

RingCentral.com is a service that can keep track of a company’s cellular activities (ex. phone calls + text messages). I had some trouble connecting with their API using PHP; here’s the basis for how I finally accomplished it.

How to log in: two legs or three legs?

First you need to decide which approach to take in authorizing users:

Two Legged (“Password Flow”) Approach

• Use the Ring Central username and password
• Ideal for running automated scripts
• A little easier to set up, but you don’t know who is logged in

Three Legged (“Authorization Code Flow”) Approach

• Each user logs into your app through Ring Central
• You have the capability of knowing who is logged in. Ideal if you need to place a call / send a text message on behalf of a specific user
• There is a time-out, such that a user will have to re-authenticate themselves after a period of time

Supposedly there’s a way to adjust (extend) the time-out, but I couldn’t get it to work. The three-legged approach meant that my users would:

1. Log into my app (through the app’s credentials)
2. Log in separately through Ring Central
3. After a period of inactivity (ex. a few hours), they’ll have to re-log in through Ring Central

Unless you need to know who is logged into your app, use the two-legged approach

Sample PHP Code to call Ring Central APIs

The following PHP code assumes that you’re using Composer, and are including that file. You’ll obviously have to fill in the variables with values unique to your app, such as the Client/Secret Keys.

PHP Code for a Two Legged Approach

The code is pretty straight forward and doesn’t need too much of an explanation:

The user gets authenticated with the Ring Central code (imported in from Composer on line 3). This is placed in a variable that gets passed into a function that calls the Ring Central API (line 32). This function uses the login info (line 8), the specific endpoint (line 13), and URL parameter (lines 15- 16).

PHP Code for a Three Legged Approach

This one does require a bit of explanation:

• First we check if the user is logged in (line 34). Assuming they’re not, they can click a link that will bring them to Ring Central to login. The link is set up in lines 12–18.
• The user logs in- on the Ring Central website- and then is brought back to your site. You need to specify the URL they are brought back to (line 13). For this tutorial, it’s a separate file and the explanation will be below.
• The user is brought to the other file (below), authenticated, and then is redirected back to the page above. A session variable is set, such that when the user comes back to this page, it passes the validation check on line 34.
• Lines 44 to 52 check if the user is actually logged in. If the user put in the wrong Ring Central credentials, you can notify them in this code block. Remember that it’s possible they could be signed out due to inactivity, which would also be caught here.
• Lines 56 to 75 actually calls the Ring Central API data, similar to above. Note though that the $platform isn’t a separate variable this time- but rather a global variable in this script.

The second file that you’ll need, to actually authenticate the user, is here:

As previously mentioned, it’ll set a session variable on line 18, and then redirect the user back to the other page (line 19).

Note: In the Ring Central sample documentation, all endpoints reference this specific file (“engine.php”). After the user is logged in, you would run a specific block of code within a switch statement to call the appropriate API endpoint.

Personal Opinion About Ring Central

They are able to accommodate all of the technical specifications required.

I’m not impressed with their Customer Support. I’ve sent several emails- on the same topic- and they come back with asking follow-up questions that I clearly provided answers for in my initial emails where I posed the question.

They were supportive when it came time to have a live video chat such I could share my screen — at which point they quickly resolved my issues.

The documentation overall is pretty good, but I found a handful of mistakes that I’ve both emailed them and Tweeted them. At the time of writing (weeks later) it still hasn’t been fixed.

• One is the wrong parameter allowed in the API, resulting no data being returned
• Others are spelling/grammar issues.