Welcome to SMS Application Walk-through

This 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:

• How to setup your repository to work with multiple environments.
• How to send a simple SMS.
• How to send a image in an SMS message, a.k.a. "MMS."
• How to track the delivery state of a message.
• How to modify the message history.
• How to reply to an SMS message.

Other Languages

This walk-through is also available in the following languages:

• PHP
• Node

Using this Walk-through

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.

Create a Project

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 setup.py 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.

$ python setup.py install

Creating an Application

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.

After 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:

• Client ID
• Client Secret
• Account Phone Number

Create Your .env File

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.

Multiple .env Files

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.

Sending an SMS

First, let's create a file called send-sms.py 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:

$ python send-sms.py

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.

Initializing the Client

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.

Authentication

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.

Troubleshooting

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.

Send an SMS

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 sender
• one or more receipients
• the message to send

SMS Sending Numbers

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"
    }
  }]
}

Processing the Response

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:

• Register the SMS being sent within an analytics system.
• Update a status record in your database.
• Etc.

If an error occurs in this step, it will be caught and handled on line 28.

Sample Response

{
  "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"
}

Up Next

Next we will learn how to send an image in an SMS message.

Download an Image

First, let's find an image to send. Kittens FTW. Right click on the image below and save it to your project directory.

Sending an Image

Just as we did before, let's create a new file called semd-mms.py 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.

$ python send-mms.py

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.

Creating the Attachments

To send an image, we need to package the text message and image file as attachments.

Attaching the Text Message

The text message is the first attachment we make, and we attach the file as application/json.

Attaching the Image

We then attach the image by reading it off of the file system.

Sending the Message

Finally, we transmit the message.

Next Up

Next we will learn how to track the delivery status of a message.

How to track delivery status of 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.py using the contents to the right. Then, let's run the script, and then follow up by explaining what is going on.

$ python track-status.py

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."

Checking the Status

This script is closely related to our first, 'send-sms.py`, except this script performs an additional step after the message is sent.

Display its Status

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.

Up Next

Next we will learn how to modify your message history.

Message Histories

Create a file called retrieve-modify.py using the contents to the right, then run the script.

$ python retrieve-modify.py

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.

Retrieve and Modify the Message History

Retrieve the List

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.

Update Message Status

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

Deleting a message is done via the HTTP DELETE method.

Next Up

Next, we will learn how to respond to an SMS message that we receive.

Replying to an SMS Message

Create a file called receive-reply.py using all the contents to the right. Then run the script:

$ python receive-reply.py

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...

Create a Handler

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.

Creating an Event Subscription

Once the handler has been created, we need to bind it to the receipt of an SMS message. We do that by:

• Create a subscription object
• Listen for the subscription.events.notification event, and bind it to our handler.
• Set the event filter to the receipt of SMS message specifically.
• Register the subscription.

Event Filters

For a full list of available event filters, please refer to our API Reference.

WebHook

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.

Congratulations!

And that's it. You should have successfully build a number of the components of an SMS application.