Tutorials>SMS API Node JS Tutorial

A tutorial to teach users to use RingCentral SMS API. Click the "Start" button below to start the tutorial.

Start Tutorial

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 send an SMS message.
  • How to send an MMS message
  • How to track the delivery status of a message.
  • How to modify the message's read status.
  • How to delete a message.
  • How to receive and reply to an SMS message.

Other Languages

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

Clone and Setup the project

$ git clone https://github.com/ringcentral-tutorials/sms-api-nodejs-demo
$ cd sms-api-nodejs-demo
$ cp .env.sample .env
$ npm install --save

Specify your app client id and client secret as well as the account login credentials to the constants defined in the .env file.

Important!

Your RingCentral app must have the SMS, ReadMessages and EditMessages permissions.

Sending an SMS message

Let's create a file named send-sms.js.

It is very convenient to access RingCentral platform using the RingCentral JS SDK.

First, we load and create an instance rcsdk of the RingCentral SDK, passing along the server, client Id and client secret loaded from the .env file.

Next, we get the platform object from the rcsdk.platform()

Then, we call the platform.login() function to authenticate a user. In this step, we pass the username and password and optionally the extension number.

After we've logged in successfully, we define the params variable and specify the from, the to and the text parameters.

Finally, we call the platform.post('/account/~/extension/~/sms', params) method to send the message.

This code will work right out of the box. So let's try it out. Go to the Terminal window and run node send-sms.js.

You should see the message delivery status output to the screen, and shortly an SMS will arrive on the recipient's phone.

You have just successfully sent an SMS programmatically from your sandbox to a recipient.

Important

Bear in mind that you can only send SMS messages from a phone number which belongs to the user who is being authenticated to use the app.

Pay attention to the params.to which is an array. This means that you can specify multiple recipients to send a group message.

Send an MMS message

Let's create a file named send-mms.js.

To send an MMS message, we use the FormData object to add content attachments to the message.

Similar to the previous step, we need to login before we move on to send a message.

First, we define the body variable, specify the from, the to and the text parameters. Then we append the body to the FormData.

Then, we load the image and append the image attachment as shown on the right-hand side pane.

Finally, we call the platform.post('/account/~/extension/~/sms', formData) method to send the message.

Let's try it out. Go to the Terminal window and run node send-mms.js.

You should see the message delivery status output to the screen, and shortly an MMS will arrive on the recipient's phone.

RingCentral supported MMS content types

  • Images: jpg/jpeg, png, gif, bmp, tif/tiff, svg
  • Videos: 3gp, mp4, mpeg, flv, wmv, mov
  • Audio: mp3
  • Files: vcf/vcard, zip, rtf, html

Attachment size limit

The maximum size for MMS is carrier-dependent and normally around 1.2MB to 1.4MB.

You can send multiple attachments in a single MMS message. But the total size of attachments should not exceed the size limit above!

Track the delivery status of a message

It takes some time for the system to send and deliver a message to a recipient. Delivering a message may fail due to networks conditions or the availability of the recipient's phone number as well. The delivery status of a particular message can be tracked using the message-store endpoint.

Let's implement the track_status() function.

After sending a message, we'll receive the response containing information about the sent message which includes the message id and the messageStatus. We'll use the messageId to identify the message we want to track the delivery status.

Inside the track_status(messageId, messageStatus) function, we check the mesasgeStatus value. If it is equal to "Queued", we cause a second delay then call the platform.get(...) method to read and print out the latest delivery status of the message.

We call the track_status() function repeatedly until we get the mesasgeStatus with other value than "Queued".

Let's try it out. Uncomment the line //track_status(jsonObj.id, jsonObj.messageStatus) then run the send_mms.js again.

Change the message read status

Every message has the readStatus as "Read" or "Unread". We can retrieve a message metadata from the message store and change the readStatus as we want.

Let's create a file named retrieve-modify.js.

Similar to the previous step, we use the SDK to login with the same user before we move on to access the message store.

To read the metadata of recent messages from the user's message store, we define the params variable and set the readStatus value to "Unread" to retrieve only unread messages.

Then, we call the platform.get('/account/~/extension/~/message-store', params) to read the message store.

We parse the response to get an array of records. We iterate thru the records array, read the message id of each message, and use the id to create an endpoint to access that message.

To change the message readStatus to "Read", we set the params.readStatus value to "Read", then call the platform.put("/account/~/extension/~/message-store/${record.id}", params) to change the readStatus of that message.

Let's try it out. Go to the Terminal window and run node retrieve-modify.js.

Specify other request parameters

You can set other request parameters such as the dateFrom and dateTo to retrieve messages created within the specified date and time period. The default date and time period is the current time minus 24 hours.

Delete a message

Let's create a file named retrieve-delete.js.

Similar to the previous step, we retrieve recent messages using the readStatus filter but this time, we read those messages which have the readStatus as "Read".

Then we iterate thru the records array, read the message id of each message, and use the id to create an endpoint to access that message, and call the platform.delete('/account/~/extension/~/message-store/${record.id}') to delete the message.

Let's try it out. Go to the Terminal window and run node retrieve-delete.js.

If you want to delete all the messages from the records array, comment out the break line.

In this step, you will learn how to listen for incoming SMS messages and new voicemail messages, then reply with an SMS message to the sender of that incoming message or incoming call.

Listen for incoming SMS and new voicemail messages

Let's create a file named receive-reply.js.

Similar to the previous step, we use the SDK to login with the same user before we move on to subscribe for notifications.

First, we call the rcsdk.createSubscription() method to get the subscription object.

Then, we define an eventFilters array and add the following filters to the array:

  • "/account/~/extension/~/message-store/instant?type=SMS": for receiving incoming SMS notifications.
  • "/account/~/extension/~/voicemail": for receiving new voicemail notifications.

As you can see, we can specify multiple event notifications in a single subscription to get notified for different types of events without the need of creating multiple subscriptions.

We use the subscription object to set the eventFilters and register for the event notifications as shown on the right-hand side pane.

Next, we implement the subscription.on(subscription.events.notification, ...) function. This is a callback function which will be called every time we receive a notification of the event we subscribed for.

As we registered for multiple event notifications, we need to detect which event notification was triggered before we take an action on the notification.

We simply check the msg.event value to see if it contains the name of the event type we've registered for.

In this tutorial, if it is the "/message-store/instant" or the "/voicemail", we parse the notification payload and create a reply message as will be discussed in the next step.

Handle other subscription situations

You can implement the subscription.on(...) function with any other event types listed below to handle different subscription situations.

- subscription.events.removeSuccess
- subscription.events.removeError
- subscription.events.renewSuccess
- subscription.events.renewError
- subscription.events.subscribeSuccess
- subscription.events.subscribeError
- subscription.events.automaticRenewSuccess
- subscription.events.automaticRenewError

Subscription limitations

Each account can register up to maximum 20 subscriptions. Therefore, using multiple event notifications in a subscription, when possible, will help overcome the limitation.

Active subscriptions will expire. The subscription object created by the SDK will renew the subscription automatically on your behalf as long as your app is still logged in and the platform refresh token is still valid.

PubNub Notification Alternative

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.

Replying with an SMS message

When there is an incoming SMS message or a new voicemail, we will receive the notification via the subscription.on(...) callback function. We parse the message body to get the sender's phone number, and we compose a message then call the sendReplySMS() function to send the message.

Then finally, we create a reply message and send it to the senderNumber.

Let's try it out. Go to the Terminal window and run node receive-reply.js.

Congratulations!

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