Getting started with RingCentral as a PHP Developer
Having been a programmer for over 30 years I have seen a lot of technology come and go. From mainframes with dumb terminals all the way up to smartphone apps. With the advent of web development in the late 90s I was thrilled with the relative ease with which websites and web-based programs could be developed. I started with a tool called iHTML and quickly switched to ASP. At the time it was clear that ASP had so many limitations that my search for the best web development language had to continue until I found PHP. It was PHP version 3 and even in this version it was able to do everything that I wanted it to do. This was the dawn of the smartphone and mobile computing so I was slightly concerned with how these new technology demands would be met with PHP. When PHP 4 came out it was already making these important connections and I was so enthralled with it that I became certified in version 4 and later in version 5.3 as well. I was the first programmer certified in this language in all of Atlantic Canada! I started a user group, and began writing articles and books on this technology. I added speaking at conferences and even helped to found one of the largest PHP developer conferences in northeastern United States and Canada. I was all-in!
As both Technologies were moving forward together (PHP and mobile computing) it was an early recommendation from Zend Corporation, the developers of PHP, to begin to develop with the mobile web first in mind. This was quite a radical recommendation at the time when you think that web development was still mostly based on desktop browser use.
Cloud computing was next to hit the mainstream for me and web development was demanding better tools and communication needs. I discovered that WordPress was among the best platforms for rapid web development and that it was based on the PHP and MySQL family of products. I dove into this technology as well, writing books, articles, plugins, conference speaking, and so on. I was seeing though that not all technology could be found in one place and that external connections were going to be needed. This realization and a need for better communications with the smartphone world made me aware of the company called RingCentral. I saw that RingCentral had many mobile cloud-based integrations that I needed within their API. They even had the APIs ready for use with many different programming languages. This multi-language platform showed me that they were basically language agnostic and that with their cloud technology for telephony I could match the two technology demands that I was facing. There were some lessons learned along the way and that is why this article was written — to help the PHP developer community with their use and integration to the RingCentral platform and how to implement their APIs within PHP. This article will be a mix of technical discussion and code samples all in an attempt to quickly get you up and running with these two great technologies and have them working together seamlessly.
RingCentral’s Developer Platform
The first thing we need to cover is how to implement the RingCentral API within PHP and then we will have an example of how it can be used to trigger SMS messages. So let’s get started with the initial steps needed to make use of the RingCentral APIs.
The first thing you will need is an account on the RingCentral developers platform. The account is free so there are no initial constraints there. Go to https://developers.ringcentral.com and create an account if you don’t already have one.
Figure 1 shows the sign up form. If you have an Adblock extension on your browser you may have to disable it in order to complete the signup process.
One of the great things about the developer environment is all the documentation, user guides, and general assistance there is available. For the beginner, once logged into your new RingCentral account hover your mouse over the Blue menu item called “Resources”. A mega-menu will appear with all kinds of helpful links; under the documentation menu you can click on the “Getting Started” link to begin working on your first application. You can also review the developer’s guide and browse all the additional tutorials that are available here. For this article however, we will click on the “Getting Started” link just to see all the options under this link. On the left hand side of the resulting page you will see links for the features that can be done within RingCentral APIs; Voice, SMS and fax, team messaging, meetings, and so. Figure 2 shows this area.
Feel free to explore these areas as you like. To continue on our tour though we are going to create a simple SMS message with the API and have it sent to a cell phone. Another great feature of the developers platform is that you can try out the API features right on the platform itself.
For our first SMS generation test in PHP to the following. Create a sample test application in your account by using the button on the top right side of the interface called “Create App”. A two-step wizard will start, page one asks you for the type of application to create. Since we are doing one that is non visual — only sending SMS messages to a phone, select “Other non-UI” in the first entry see area [1] of figure 3.
This figure also shows some other options you can select on the first page. Area [2] cannot be changed in this instance as we are only starting a Sandbox test application. At area [3] click “No” for this option as again we are only doing a test application.
Click next to go to the second page in the application creation wizard. Here we get to name our application. Let’s call it “SMS testing” [1] and give it a meaningful description [2]. Figure 4 shows these options filled in. On the app permissions drop-down [3] you can indicate what portions of the API you need to use in your application. Since we are only planning on sending SMS messages and related features, simply find SMS on the drop-down list and select it. You can set the options that follow like adjusting the display name [4] or using an application icon but these are not needed for our test app. Click on the create button to finish the wizard and indeed create the application. You should see a congratulatory dialogue message, click “OK” and you will be taken to the details page for your newly created application. Here you can take note of the dashboard display but you will eventually need the values from the credentials page so be sure to take a look there as well. You can navigate to the different pages within the menu on the left.
Figure 5 shows the successful creation of our “SMS Testing” application.
Now we want to use this app for our sample testing from within the developers platform itself. This helps us to ensure we have created the app properly before we start using it through the API on our PHP websites. (Don’t worry, I haven’t forgotten the main point of this article!) On the Blue menu hover over the resources menu and click on “SMS” under the “API Reference” submenu. You will be taken to a web page that looks like that of Figure 6.
This is the quick access method to this page but you can also click on the API reference menu item itself and select items [1] and [2] as shown in Figure 6.
To test out the application from this page you first have to make sure you are testing the correct application. If you have multiple applications connected to your developer account simply click the “Change App” button shown in figure 7 and select the app from the drop-down, making sure you are in the sandbox category.
Next fill in the required information noted in [2], [3], and [4]. The phone number that the SMS will be sent from, the phone numbers that the SMS will be sent to, and the text message itself respectively. The “from” number [2] can be located on the apps dashboard under the sandbox credential section in the account field. Of important note here is the area on the right hand side of the screen shown in figure 7 at [5]. Here you can see the sample code in multiple languages and below that the response codes from the app when it executes with the given inputs. You will get either a 400 error notice on failure or a 200 okay display on success showing the parameters that were used. If the test was successful you should also receive an actual SMS text message to the phone number provided similar to that shown in figure 8.
Just a note that the account ID and the extension ID form Fields further down on this page should both be set to “~”. We will discuss these values when we get into the actual PHP API code a little later in this article. Also all fields under “Country” should be left blank.
Getting back to the sample application and testing it within the developers platform, once you send a successful text you can copy the 200 output metadata to see what the response looks like. Listing 1 shows this for our successful example SMS message.
You can also copy the sample PHP code if desired but we will make our example a little less complex to start with and then add complexity as we work through the PHP code.
RingCentral’s API within PHP
So let’s consider how to actually make these API calls within a PHP environment. I have created a subdomain on my main PHP server where I can build my tests. Consider doing the same if you are able. The first thing to consider is the inclusion of the API Library within your environment. If you use PHP’s composer tool then this is quite simple to do. The SDK for PHP is located on GitHub here: https://github.com/ringcentral/ringcentral-php
and the composer instructions are in the readme file here:
https://github.com/ringcentral/ringcentral-php/blob/master/README.md
Since I am using the API on my server I actually have to run my composer actions on my localhost environment on my desktop computer and then upload the installed files and folders to my subdomain for use “up” there. Once the files and folders are installed with composer on the localhost you should see two folders created; one called “RingAPI” and the other one called “vendor”. Simply upload these two folders and all their containing files to your subdomain location as two separate subfolders. Your file folder structure should look similar to that figure 9.
The first thing we want to do is to connect PHP to our RingCentral API library and verify our credentials from our SMS testing app. To find your full list of credentials select your application in the developers portal and click on “Credentials” on the left-hand menu.
The main code file here we are using is called rc-sms.php (listing 2).
In this file we are requiring (importing) a file that holds our API functions and other supporting information. The functions file is shown in listing 3 and is called rc-functions.inc.
I have left in some commented code to help you with debugging and custom controlled outputs (echos) so you can play with the code yourself and see some of the browser outputs.
Our main code file does two simple things after connecting to the functions file, it checks to see if the SDK can be connected to and then it attempts to send our SMS message. We test the connection to the SDK with a call to the function named rc_sdk_check() and return a 1 or 0 for pass-fail results. In the check function we call another function to retrieve our connection credentials called rc_sdk_params(). In our sample these values are hard-coded but they should be stored in a database and protected with suitable encryption. Once we have these credentials returned to us in an array we use the ID, secret key, and URL array values to attempt to create a connection object called $sdk. We then use the connection object in a try /catch block to attempt a login method call with the rest of our credential parameters and depending on pass or fail we return the 1 or 0 value. The actual connection to the API code is found in the first line of code:
require(‘vendor/autoload.php’);This brings in the RingCentral API library for our use.
Going back to the main code file, we see messages echoed to the browser based on the returned pass or fail results. We then test the sending of an SMS message based on the same API calls since we know that the API is responding properly. We could have embedded the RingCentral send SMS function within the first if / then block of code, but for clarity of reading the code we kept them separate. Inside the RingCentral send SMS function we receive the mobile phone number of the person we are sending a message to and their full name, to make the message more personable, as functional parameters. For Simplicity we again have hard-coded these values. This could easily be information that can be entered by a web data entry form.
Then we sent the message we are we wanting to text and the number that it is coming from. The “from” number could be taken from our app credentials but again for ease of viewing we are hard coding it here. Next we make our SDK connection and start another try /catch block to send out the SMS.
This line of code is one of the most important ones:
The “/sms” at the end of the first portion of the post method call tells the SDK handle we have stored in $sdk that we want to use the SMS portion of the RingCentral API and then we pass in our other related values in an array.
If the “try” portion passes then the SMS is sent out and you should get a text message like that shown in Figure 10.
That is all there really is to making use of the RingCentral API within PHP. Each API endpoint has slightly different credentials and parameters so be sure to explore each of these in the developers platform documentation when the need or interest to use these other areas arises. Also, remember to adjust your application on the development platform to include the other API features via the API permissions list if you want to employ them in your PHP code.
I hope you enjoyed this guided tour and have seen just how easy it really is to use the RingCentral API within the PHP environment.
Happy PHP API ing!
Also please let us know what you think by leaving your questions and comments below. To learn even more about other features make sure to visit the RingCentral developer site and if you’re ever stuck make sure to go to the RingCentral developer forum.
Want to stay up to date and in the know about new APIs and features? Join the Game Changer Program and earn great rewards for building your skills and learning more about RingCentral!
