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-csharp-demo
$ cd sms-api-csharp-demo
$ open sms-api-csharp-demo.sln
Specify your app client id and client secret as well as account login credentials to the constant defined within the brackets "< >".
Let's create a function named send_sms() as shown on the right-hand side pane.
It is very convenient to access RingCentral platform using the RingCentral.Net SDK.
First, we create an instance of the RingCentral.Net SDK RestClient and passing along the client Id and client secret. We also specify the platform environment and in this demo, we set the last parameter to false to access the sandbox environment.
Then, we call the Authorize function to authenticate a user. In this step, we pass the username and password and optionally the extension number.
We need to verify if we've logged in successfully by checking the rc.token.access_token.Length before we use the SDK to call platform APIs.
We create an instance of the CreateSMSMessage object and set the required query parameters, which include the from, to and the text message.
Finally, we call the rc.Restapi().Account().Extension().Sms().Post(parameters); method to send the message.
This code will work right out of the box. So let's try it out. Go to the Main function and uncomment the line //send_sms().Wait(); then run the app.
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 parameters.to which is an array. This means that you can specify multiple recipients to send a group message.
Let's continue to create a function named send_mms() as shown on the right-hand side pane.
Sending an MMS message is very much similar to sending an SMS message, except we add content attachments to the text message.
We follow the same step to create an instance of the RingCentral.Net SDK RestClient, call the Authorize method and check the access token before sending a message.
In addition to specifying the from, the to and the text query parameters, we create an attachment to hold the binary content and add the attachment to the attachments array. This means that we can send multiple attachments in a single MMS message.
Finally, we call the rc.Restapi().Account().Extension().Sms().Post(parameters, attachments); method to send the message.
Let's try it out. Go to the Main function and uncomment the line //send_mms().Wait(); then run the app.
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. The delivery status of a particular message can be tracked using the message-store endpoint.
After sending the MMS message in the previous step, we call the track_status() method, passing along the instance of the SDK, the messageId and the messageStatus. We'll use the messageId to identify the message we want to track the delivery status.
Inside the track_status() method, we implement a while loop and check if the mesasgeStatus value is equal to "Queued", we cause a second delay then call the MessageStore(id).Get() method to read and print out the latest delivery status of the message.
Let's try it out. Uncomment the line //track_status(rc, resp.id, resp.messageStatus).Wait(); then run the app 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 implement the retrieve_modify() method.
To read the metadata of recent messages from the user's message store, we create an instance of the ListMessagesParameters object, set the requestParams.readStatus to "Unread" so we retrieve only recent unread messages from the message store. Then we call the MessageStore().List(requestParams);
The JSON response resp contains an array of records. We iterate thru the records array, read the message id, create and instance of the UpdateMessageRequest object and set the updateRequest.readStatus to "Read". Then we call the MessageStore(messageId).Put(updateRequest); to change the readStatus of that message.
Let's try it out. Go to the Main function and uncomment the line //retrieve_modify().Wait(); then run the app.
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 implement the retrieve_delete() method.
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, and call the MessageStore(messageId).Delete(); to delete the message.
Let's try it out. Go to the Main function and uncomment the line //retrieve_delete().Wait(); then run the app.
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 message, then reply with an SMS message to the sender of that incoming message or incoming call.
Let's implement the receive_reply() method.
We follow the same step to create an instance of the RingCentral.Net SDK RestClient, call the Authorize method and check the access token before moving on to execute the codes.
First, we create 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.
Then, we create an instance of the Subscription object, passing along the rc and the eventFilters parameters. The last parameter is a callback function which will be called every time we receive a notification of the event we subscribed for. Within the callback function, we will call the reply_sms_message() method, which will be implemented in the next step.
Next, we call the subscription.Subscribe() method to register for the event notification.
We also create a while loop to keep the process running so we can test the demo app. We use the waitLoop flag to terminate the process when we set its value to false.
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 call the replySMSMessage() function, passing along the rc and the message objects.
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 jsonObj["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 message body to get the sender's phone number, and we compose a message then send the message to the senderNumber.
Let's try it out. Go to the Main function and uncomment the line //receive_reply().Wait(); then run the app.
If you don't want to terminate the process after receiving and replying a message, comment out the waitLoop = false line.
And that's it. You should have successfully build a number of the components of an SMS application.