Using RingCentral Toll-Free SMS APIs

Toll-Free SMS is the ability to send and receive SMS text messages on a toll-free number. In the US, this means numbers with toll-free area codes including 800, 888, 877, 866, 855, 844, and 833. A popular reason to use toll-free numbers for SMS is that they can be used for high-volume Application-to-Person (A2P) messaging and are much easier to gets started with and less expensive than Short Codes, which require a lengthy application and approval process.

This article covers why toll-free number SMS is useful and how to send and receive messages for toll-free SMS via the RingCentral API.

You might also like:  Build and Graduate Your App in RingCentral

Why Toll-Free SMS?

Toll-Free SMS can be a quick way to implement A2P SMS which can be used for many important business communication needs, including:

• Special offers and coupons to many users, e.g. over 100 recipients
• Appointment reminders such as from dental and doctors offices sending appointment reminders and asking for confirmations
• Service alerts such as when your car repairs have been completed and your car is ready for pick up
• Notifications, on yur account including fraud alerts and airline flight updates

Compared to short codes, the other option for A2P, Toll-Free SMS also does not require an application and approval process such as needed for short codes and is much less expensive.

Compliance With CTIA P2P and A2P Guidelines

In addition to the business reasons, it is important to comply with CTIA wireless industry trade association guidelines in the Messaging Principles and Best Practices Guide. While it may be easy to get started using APIs with local phone numbers for automated SMS, if your SMS doesn't fit the P2P SMS profile, your text messages may be blocked by wireless carriers.

Specifically, P2P guidelines are subject to the following limitations:

• 1 message per second
• 1,000 messages per day
• 1 number being used
• 100 max recipients
• 1:1 send to receive ratio
• 25 max repetitive messages

Any texting that falls outside of this may be considered A2P and blocked by the "Service Provider’s Unwanted Messaging threat mitigation efforts consistent with a Service Provider’s individual messaging service terms and conditions." If your SMS texting doesn't fit this profile, consider switching to toll-free number SMS.

How to Send and Receive Toll-Free SMS

A number of different providers offer toll-free number SMS APIs. Often, it is as easy as getting a toll-free number provisioned and then using the toll-free number in the API rather than a standard long code.

Sending Toll-Free SMS

For example, using the RingCentral API, you can send a toll-free number SMS as easy as using the Create SMS Message API:

POST https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~/sms

{
  "to": { "phoneNumber": "+16505550100"},
  "from": { "phoneNumber": "+18005550200"},
  "text": "Flight information"
}

Checking Toll-Free SMS Send Status

The response will contain a message ID that can be used to retrieve the current send status in the status property. Messages are queued so you will not receive the status synchronously.

You can use the Get Message List API to get a list without a specific message ID or the Get Message API using the message ID:

GET /restapi/v1.0/account/~/extension/~/message-store/33333333

  Response  HTTP 200 OK

{
 "uri" : "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/message-store/33333333",
  "id" : 33333333,
  "to" : [ {
    "phoneNumber" : "+16505550100",
    "location" : "San Mateo, CA"
  } ],
  "from" : {
    "phoneNumber" : "+18005550200"
  },
  "type" : "SMS",
  "creationTime" : "2019-09-18T13:24:50.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 60279564004,
    "uri" : "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/message-store/33333333/content/44444444",
    "type" : "Text",
    "contentType" : "text/plain"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "Flight information",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 5578984350117917661,
  "lastModifiedTime" : "2015-02-18T13:24:50.300Z"
}

Receiving Toll-Free SMS

You can use the Get Message List API to check for Inbound messages for messages that have been received or you can use webhooks or PubNub notifications to receive messages as they arrive. The Instant Message Event for webhooks and PubNub looks like the following:

{
    "uuid":"ed1cf00c-0420-4bf5-a0ae-e659bb9f77e0",
    "event": "/restapi/v1.0/account/11111111/extension/22222222/message-store/instant?type=SMS",
    "subscriptionId": "dc853541-66ac-45d8-a289-1a239fd72888",
    "ownerId": "823476228762",
    "timestamp": "2013-06-14T12:00:00.000Z",
    "body": {
           "id" : "606090030016",
           "to" : [ {
              "phoneNumber" : "+18005550500",
              "location" : "San Mateo, CA"
           } ],
           "from" : {
              "phoneNumber" : "+16505550200"
           },
           "type" : "SMS",
           "creationTime" : "2016-02-22T17:01:00.000Z",
           "lastModifiedTime" : "2016-02-22T17:01:00.000Z",
           "readStatus" : "Unread", 
           "priority" : "Normal",
           "attachments" : [ {
             "uri" : "/restapi/v1.0/account/~/extension/22222222/message-store/33333333/content/55555555"
             "id" : "55555555",
             "type" : "Text",
             "contentType" : "text/plain",
             "size": 4096
             } ],
           "direction" : "Inbound",
           "availability" : "Alive",
           "subject" : "confirmed",
           "messageStatus" : "Received",
           "conversationId" : "7876416245344257449"
        }
}

Thanks for reading!

Further Reading

Work With RingCentral APIs

Messaging APIs of RingCentral