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 403error 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/