A quickstart tutorial to teach users to use RingCentral SMS API. Click the "Start" button below to start the tutorial.
Start TutorialThis walk-through of an SMS application will show you how to go about building a fully functional SMS application. In this walk-through you will learn:
This walk-through is also available in the following languages:
Navigation controls are located above this text. Use to move to the next step of the tutorial. Use to move to the previous step of the tutorial (if there is one). Use to see an overview of all the steps in the tutorial.
Let's begin where every new software project begins: setting up your local development environment and preparing your workspace to code. In node, we do this by creating a directory to hold our project files. The first file we create is our composer.json
file which defines our project name, and our dependencies. Create this file using the contents to the right.
Then, go to the command line, and install your prerequisites.
$ php composer.phar install
Now, let's setup RingCentral and your environment.
The first step is to login to the RingCentral Developer Portal, and create an app. You can do this easily by clicking the button/link below, and then clicking the "Create" button.
You can safely ignore the Redirect URI field.
Create SMS ApplicationAfter creating the app, you will be taken to the app's dashboard. Make note of the following, as we will be using this in setting up your environment:
The ability to create a single software package that can be easily deployed to any environment is a modern-day essential. Therefore, we will begin with this fundamental setup, by placing all of our environment specific variables in a config file (of sorts).
Create a copy of the provided .env.sample
file and name it .env
. Edit this new file and enter in the various variables accordingly.
Name | Help/Description |
---|---|
RINGCENTRAL_CLIENT_ID |
Enter in the Client ID provided to you after creating your application. |
RINGCENTRAL_CLIENT_SECRET |
Enter in the Client Secret provided to you after creating your application. |
RINGCENTRAL_USERNAME |
Enter the phone number provisioned to you when you setup your RingCentral account. If you choose to use your company's phone number, rather than your direct line, then you will also need to specify an extension below. |
RINGCENTRAL_EXTENSION |
Enter the extension corresponding to the user who will authenticate into the app. This is not necessary if you used your direct line number above. |
RINGCENTRAL_PASSWORD |
Enter in the password you specified when you created your RingCentral account. |
RINGCENTRAL_RECEIVER |
Enter in any phone number you would like to receive an SMS. Obviously you may want to move this variable outside of the environment and bind it to a customer phone number or something else. |
Placing the variables in a .env
file will make it much easier down the road when you need to deploy the same code base to production. In fact, you might have a different configuration for your QA and/or staging environments. Create as many .env
files as you need.
First, let's create a file called send-sms.php
and place within it the code to the right. This script will work right out of the box. So let's try it out. Go to the console and run this command:
$ php send-sms.php
You should see the message Id output to the screen, and shortly an SMS will arrive on the recipient's phone.
Now, let's walk-through the code to see what just happened.
The first thing we do is load the environment variables within the .env
file you created in the previous step. Then using those variables, we instantiate a new javascript client.
Before making any call to the RingCentral API, one must authenticate their client. In this sample application we are authenticating using our own username and password. That means the SMS we send, will appear to the recipient to be sent from us - or the phone number used when we authenticated to the API. Depending upon your requirements your application may want to use OAuth to capture the credentials of another user and send an SMS on their behalf. For this scenario however, we are going to keep things simple and leave well enough alone.
It is not uncommon for developers to need additional help when authenticating for the first time. If you have trouble, check the list below for help.
Are you authenticating using a personal phone number?
Bear in mind that the RINGCENTRAL_USERNAME
environment variable should point to a RingCentral phone number, not your personal phone number.
Are you authenticating using your company phone number?
If you authenticating using your company's main phone number, then you must also specify your user's phone extension in order to properly identify your account specifically. You do not need to specify an extension if you are authenticating using your direct line.
After authentication, the platform
object has now been seeded with an authorization token allowing you to access all the APIs your application has permission to use. So now, it's time to send an SMS. The API allows you to identify:
The phone number used to identify the sender of the message must have permission or the authority to send an SMS. To determine which phone numbers a user can use to send and receive SMS, retrieve the user's list of phone numbers from the extension/phone-number endpoint and then filter that list by numbers with the SmsSender
feature. A user record might look like the below. Note the features
element which identified if the corresponding phone number can send an SMS.
{
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/phone-number?page=1&perPage=100",
"records":[{
"id":33333333,
"phoneNumber":"+16505551212",
"paymentType":"Local",
"type":"VoiceFax",
"usageType":"DirectNumber",
"features":[
"SmsSender",
"CallerId"
],
"status":"Normal",
"country":{
"uri":"https://platform.devtest.ringcentral.com/restapi/v1.0/dictionary/country/1",
"id":"1",
"name":"United States"
}
}]
}
Upon successfully sending the SMS, you may want to take additional action. For example, you may want to log that the SMS was sent as shown in this sample application. Other things you may want to do:
If an error occurs in this step, it will be caught and handled on line 28.
{
"uri" : "https://platform.ringcentral.com/account/1346632010/extension/1346632010/message-store/315450330010",
"id" : 315450330010,
"to" : [ {
"phoneNumber" : "+18551003738"
} ],
"from" : {
"phoneNumber" : "+18559100010"
},
"type" : "SMS",
"creationTime" : "2012-09-13T15:21:08.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : "https://platform.ringcentral.com/account/1346632010/extension/1346632010/message-store/315450330010/content/1",
"contentType" : "text/plain"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"subject" : "Test SMS message from Platform server",
"messageStatus" : "Sent",
"conversationId" : 4481650717038104652,
"lastModifiedTime" : "2012-09-13T15:21:09.000Z"
}
Next we will learn how to send an image in an SMS message.
First, let's find an image to send. Kittens FTW. Right click on the image below and save it to your project directory.
Just as we did before, let's create a new file called semd-mms.php
using the contents to the right. This script will work right out of the box. So let's first run it, and then walk-through the code in more detail to understand how it worked.
$ php send-mms.php
You should see the message Id output to the screen, and shortly an SMS will arrive on the recipient's phone.
Next we will walk through this file to highlight the key differences from sending a purely text message.
To send an image, we need to package the text message and image file as attachments.
The text message is the first attachment we make, and we attach the file as application/json
.
We then attach the image by reading it off of the file system.
Finally, we transmit the message.
Next we will learn how to track the delivery status of a message.
Once a message has been sent, you can check to see if it was successfully delivered. In this example, you should observe how the basic structure of the script mirrors that of the previous examples. We initialize the client, authenticate, and so forth. Let's begin as before: create a new file called track-status.php
using the contents to the right. Then, let's run the script, and then follow up by explaining what is going on.
$ php track-status.php
Running the above script should result in a response saying the message's status is "Queued." A message will be delivered to the recipient shortly, at which point the status will change to "Delivered."
This script is closely related to our first, 'send-sms.php`, except this script performs an additional step after the message is sent.
We retrieve the message ID returned to us when we sent the message. We then use that message ID when we place a call to the message-store
endpoint. A typical response will look something like this:
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/12502999004/extension/12502999004/message-store/60279564004",
"id" : 60279564004,
"to" : [ {
"phoneNumber" : "+16505393204",
"location" : "San Mateo, CA"
} ],
"from" : {
"phoneNumber" : "+18889450052"
},
"type" : "SMS",
"creationTime" : "2015-02-18T13:24:50.000Z",
"readStatus" : "Read",
"priority" : "Normal",
"attachments" : [ {
"id" : 60279564004,
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/12502999004/extension/12502999004/message-store/60279564004/content/60279564004",
"type" : "Text",
"contentType" : "text/plain"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"subject" : "Flight information",
"messageStatus" : "Sent",
"smsSendingAttemptsCount" : 1,
"conversationId" : 5578984350117917661,
"lastModifiedTime" : "2015-02-18T13:24:50.300Z"
}
If the message was sent properly, then the text "Delivered" will be printed to the console.
Next we will learn how to modify your message history.
Create a file called retrieve-modify.php
using the contents to the right, then run the script.
$ php retrieve-modify.php
You will see that a message has been deleted, and a status changed. Let's explore this in more detail so you understand what happened.
In this example, we retrieve a list of messages and pick the first one in the list to modify. In your application, you almost certainly will rely on different logic, but the basic pattern is the same. Here we retrieve a list of messages sent after a specific date. Then we just arbitrarily choose the first message returned to us.
Next, we update the record using HTTP PUT
. We transmit only the properties we want to change. In this case, we set readStatus
to "Read" and then visually confirm that the status was changed by outputting the status returned to us in the response.
Deleting a message is done via the HTTP DELETE
method.
Next, we will learn how to respond to an SMS message that we receive.
Create a file called receive-reply.php
using all the contents to the right. Then run the script:
$ php receive-reply.php
This script will start and then wait until an SMS is received. Let's trigger the app to send an SMS in reply to one we send. Send an SMS from your personal phone to the phone number you set RINGCENTRAL_USERNAME
to. You should shortly receive an auto-response to your phone.
Here is how it works...
First, we create a function to send the auto-response. This function will receive as input the message that we will be responding to. We use this message to set the receipint of our response.
Once the handler has been created, we need to bind it to the receipt of an SMS message. We do that by:
subscription.events.notification
event, and bind it to our handler.For a full list of available event filters, please refer to our API Reference.
The subscription we created above uses PubNub.
There is also a WebHook way to do subscription. We won't dive into detail here. You can click the link to read more.
And that's it. You should have successfully build a number of the components of an SMS application.