SMS APIs — Tips, Tricks and Quirks
The Business SMS feature has been a popular offering by RingCentral. It allows you to send professional text and multimedia messages to colleagues, clients, and departments from your business number. In this article we’ll cover benefits of RingCentral SMS along with various tips for using the SMS API.
RingCentral SMS Benefits
There are multiple benefits to using RingCentral for SMS including the following popular reasons:
- Single number: You can use one business number for calling , texting, faxing and sending multimedia files. You can send and receive unlimited local texts with up to 1000 characters between extensions within your organization or to any local numbers.*
- Multiple endpoints: There are several ways you could send and receive text messages with RingCentral SMS features — RingCentral Desktop app, Glip , RingCentral Mobile App and also via RingCentral iWatch app.
- Custom integrations: RingCentral’s SMS API allows you to integrate SMS feature within your custom application. We already have 100s of our customers using this feature in their private and publicly available custom softwares, home grown and publicly available CRM applications.
To get access to the APIs, you need to signup to RingCentral Developer Program and create your developer account and create a RingCentral Application. For further information on this, you could visit : https://developer.ringcentral.com/library/getting-started.html
You could also read this article: https://medium.com/ringcentral-developers/use-message-sync-api-to-archive-your-sms-fax-and-voicemail-messages-cd23748e188f and read this section : Create a new RingCentral app
General Errors while using SMS APIs and Tips to resolve them:
Choosing the right “From” number from your extension to send SMS via API
RingCentral account can have multiple user extensions and each user extension is assigned to one or more Digital Lines or Direct Numbers.
Lets assume user John Smith is assigned ext. 105 and ext. 105 has:
- Digital Line — +1 (408) XXX XXXX
- Direct Numbers — +1 (650) XXX XXXX and +1 (619) XXX XXXX.
You can choose one of the above numbers as “From” number for sending SMSs . No other numbers can be assigned as “From” numbers.
Using the API, you can get a list of these numbers by calling the following API an filtering for numbers that have SmsSender
, MmsSender
, or InternationalSmsSender
in the features
array:
GET /restapi/v1.0/account/{acctId}/extension/{extId}/phone-numbers
You will get a response like the following:
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/809646016/extension/809646016/phone-number?page=1&perPage=100",
"records" : [
{
"id" : 556104016,
"phoneNumber" : "+1720XXXXXXX",
"paymentType" : "Local",
"location" : "Smoky Hill, CO",
"type" : "VoiceFax",
"usageType" : "DirectNumber",
"status" : "Normal",
"country" : {
"uri" : "https://platform.ringcentral.com/restapi/v1.0/dictionary/country/1",
"id" : "1",
"name" : "United States"
},
"features" : [ "InternationalSmsSender", "CallerId", "MmsSender", "SmsSender" ]
}
]
...
}
If you use another number that does not belong to the extension that authorized your access token, you will get the following 403
error message:
Phone number doesn’t belong to extension
Missing SMS permission
If there is no SMS permission added to the RC Developer App , you will get a 403 Forbidden
error with error message —
In order to call this API endpoint, application needs to have [SMS] permission
with error code CMN 401 — Insufficient Permission
Missing SMS feature
If the number that belongs to extension doesn’t have SMS feature enabled for it, you will get the following 403
error MSG 252
:
Invalid sender phone number [${fromPhoneNumber}]: SMS messages are not supported for this number
Also, if the number is a fax only, number, you will receive the following 403
error MSG 241
:
Invalid sender phone number [${fromPhoneNumber}]: cannot send SMS message from fax-only number
Server issues while sending SMS:
There are chances that something went wrong on the server side , and you recieve HTTP Status 503
with error code — MSG 290
and the following error message
Sending SMS to ${toPhoneNumber} failed. Please try later
Just retry sending message after couple seconds — to be precise read the Retry After
response header and resend the SMS after the stated number of seconds.
Next Steps
Feel free to comment on this blog to add more commonly seen SMS issues/errors and I shall edit this blog and add few more tips/quirks on how to handle those issues.
Thats it. Now you are ready to rock and roll :)
To learn more about RingCentral Developer Program and start building cool integrations using RingCentral API’s visit https://developer.ringcentral.com/
For other RingCentral Developer Program related articles, visit our medium page by clicking here.
Learn more about our Developer Program here:https://developer.ringcentral.com/