A 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:
$ 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.
Your RingCentral app must have the SMS, ReadMessages and EditMessages permissions.
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.
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.
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.
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!
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.
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.
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.
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.
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:
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.
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
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.
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.
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.
And that's it. You should have successfully build a number of the components of an SMS application.