Sending an SMS

Last updated: 2022-08-22 Contributors EKozahByrne ReeseNoneJohn WangPaco Vu
Edit this page

First time sending an SMS?

If you are new to RingCentral and are trying to send an SMS for the first time, we recommend you try our SMS Quick Start Guide available in multiple languages, and checking out our SMS Best Practices Guide.

SMS messages can be sent to or received from the handsets operated by most mobile carriers (all major US carriers are currently supported). Each SMS is a peer-to-peer message from one phone number to another. There is a special SMS API endpoint to create and send SMS messages.

POST /restapi/v1.0/account/~/extension/~/sms HTTP/1.1
Content-Type: application/json   
Content-Length: ACTUAL_CONTENT_LENGTH_HERE

{
   "to": [{"phoneNumber": "14155550100"}],
   "from": {"phoneNumber": "16505550100"},
   "text": "Test SMS message"
}   
HTTP/1.1 200 OK
Content-Type: application/json  

{
   "uri": ".../account/1346632010/extension/1346632010/message-store/320270670010",
   "id": 320270670010,
   "to": [{"phoneNumber": "14155553732"}],
   "from": {"phoneNumber": "16505550010"},
   "type": "SMS",
   "creationTime": "2012-10-16T06:34:58.000Z",
   "readStatus": "Unread",
   "priority": "Normal",
   "attachments": [   {
      "id": 1,
      "uri": ".../account/1346632010/extension/1346632010/message-store/320270670010/content/1",
      "contentType": "text/plain"
   }],
   "direction": "Outbound",
   "availability": "Alive",
   "subject": "Test SMS message",
   "messageStatus": "Sent",
   "conversationId": 4178398077955743750,
   "lastModifiedTime": "2012-10-16T06:34:59.000Z"
}

Send an SMS

Select your preferred language below.

Install RingCentral JavaScript SDK

$ npm install @ringcentral/sdk dotenv --save

Create and edit sms.js

Create a file called sms.js. Be sure the values in your .env file have been set properly, including the SMS_RECIPIENT variable.

/* You get the environment parameters from your 
   application dashbord in your developer account 
   https://developers.ringcentral.com */

const SDK = require('@ringcentral/sdk').SDK
require('dotenv').config();

const RECIPIENT    = process.env.SMS_RECIPIENT

var rcsdk = new SDK({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});

var platform = rcsdk.platform();

  platform.login({
    'username':  process.env.RC_USERNAME,
    'password':  process.env.RC_PASSWORD,
    'extension': process.env.RC_EXTENSION
})

platform.on(platform.events.loginSuccess, function(e){
    read_extension_phone_number()
});

async function read_extension_phone_number(){
    try {

        var resp = await platform.get("/restapi/v1.0/account/~/extension/~/phone-number")
        var jsonObj = await resp.json()
        for (var record of jsonObj.records){
            for (feature of record.features){
                if (feature == "SmsSender"){
                    return send_sms(record.phoneNumber)
                }
            }
        }
    } catch(e) {
        console.log(e.message)
        process.exit(1)
    }
}

async function send_sms(fromNumber){
    try {

        var resp = await platform.post('/restapi/v1.0/account/~/extension/~/sms', {
            from: {'phoneNumber': fromNumber},
            to: [{'phoneNumber': RECIPIENT}],
            text: 'Hello World!'
        })
        var jsonObj = await resp.json()
        console.log("SMS sent. Message status: " + jsonObj.messageStatus)
    } catch(e) {
        console.log(e.message)
        process.exit(1)
    }
}

Run your code

You are almost done. Now run your script.

$ node sms.js

Install RingCentral Python SDK

$ pip install ringcentral python-dotenv

Create and edit sms.py

Create a file called sms.py. Be sure the values in your .env file have been set properly, including the SMS_RECIPIENT variable.

#!/usr/bin/python

# You get the environment parameters from your 
# application dashbord in your developer account 
# https://developers.ringcentral.com

from ringcentral import SDK
import os,sys

from dotenv import load_dotenv
load_dotenv()

RECIPIENT    = os.environ.get('SMS_RECIPIENT')

rcsdk = SDK( os.environ.get('RC_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()

try:
  platform.login(os.environ.get('RC_USERNAME'),
                 os.environ.get('RC_EXTENSION'),
                 os.environ.get('RC_PASSWORD') )
except:
  sys.exit("Unable to authenticate to platform. Check credentials.")

def read_extension_phone_number():
  try:
    resp = platform.get("/restapi/v1.0/account/~/extension/~/phone-number")
    jsonObj = resp.json()
  except e:
    sys.exit("Unable to fetch SMS-enabled phone numbers")
  for record in jsonObj.records:
    for feature in record.features:
      if feature == "SmsSender":
        return send_sms(record.phoneNumber)
  sys.exit("No SMS-enabled phone number found")

def send_sms(fromNumber):
  try:
    resp = platform.post('/restapi/v1.0/account/~/extension/~/sms',
    {
        'from' : { 'phoneNumber': fromNumber },
        'to'   : [ {'phoneNumber': RECIPIENT} ],
        'text' : 'Hello World!'
    })
    jsonObj = resp.json()
  except:
    sys.exit("Unable to send SMS")
  print (jsonObj.messageStatus)

read_extension_phone_number()

Run your code

You are almost done. Now run your script.

$ python sms.py

Sending an SMS on Behalf of a Call Queue

Sending SMS messages on behalf of a call queue (Department type extension) is allowed. To send an SMS message from the Department direct phone number, the user should be logged in as the department manager (with department credentials). When requesting a phone number list for a Department extension type, SmsSender flag set for department numbers is returned.

Sending an SMS to Disabled and Frozen Extensions

Sending SMS messages to Disabled and Frozen extension types is not allowed. When an SMS message is sent to a Disabled/Frozen extension, it is dropped. The dropped message is saved only in the sender's outbox.