Overview

Last updated: 2024-08-15

Contributors

SMS templates are reusable messages that you would frequently need to send your users as SMS messages. They are predefined text messages that can contain text and URLs.

Each SMS template can have maximum 1000 UTF-16 encoded characters. This is also the maximum length of a single SMS message (sent in MMS format) that can be sent out from a RingCentral phone number.

RingCentral platform provides APIs to manage SMS templates for 2 scopes, company templates and user templates (a.k.a personal templates).

Company SMS templates

Company SMS templates can be created, listed, modified and deleted only by users who have the "Edit Company SMS Templates" user permission, this user permission normally included in the default super admin user role. If you want to grant the "Edit Company SMS Templates" permission to other user roles, make sure that the permission is selected for that role.

Company SMS templates can be created for different sites under an account. Each account can have maximum up to 50 predefined company SMS templates. This number includes those templates created for any site under the same account.

The company SMS template name must be unique across all sites. If the same name is reused, the template creation API will fail.

Browse the Company SMS template APIs reference to try online.

User SMS templates

User SMS templates are personal resource. They can be created, listed, managed and accessed by a user who have the "Business SMS" user permission. And the templates are only accessible by that user.

Each user can create maximum up to 25 predefined user SMS templates. A user SMS template name must be unique. If the same name is reused, the template creation API will fail.

Note

Any user with the "Business SMS" user permission can also read the company SMS templates using the user SMS template API by setting the "scope" query parameter to "all" or "company".

Browse the User SMS template APIs reference to try online.

Example of a use case of a user SMS template

Imagine if you are a community manager and you need to send an SMS message every month to remind your community members about the monthly meetup. You can compose the SMS message once, save it as a template. Then every month you need to send the reminder, you can simply load the SMS message from the template and use it to send out the reminder to your community members.

Example code to create a user SMS template

Running the code

If you have tried the SMS quick start, you can just copy all the functions below and add them to the quick start project then call the create_user_sms_template() function. Otherwise, edit the variables in ALL CAPS with your app and user credentials before running the code.
The C# code requires the .NET SDK version 6.2.0 (or newer if available).
The Java code requires the Java SDK version 3.2.0 (or newer if available).

JavaScript

const RC = require('@ringcentral/sdk').SDK

// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
    server: "https://platform.ringcentral.com",
    clientId: "RC_APP_CLIENT_ID",
    clientSecret: "RC_APP_CLIENT_SECRET"
});
var platform = rcsdk.platform();

/* Authenticate a user using a personal JWT token */
platform.login({ jwt: "RC_USER_JWT" })

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

platform.on(platform.events.loginError, function(e){
    console.log("Unable to authenticate to platform. Check credentials.", e.message)
    process.exit(1)
});

/*
  Create a personal reusable SMS template
*/
async function create_user_sms_template(){
  try {
      let endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates"
      let bodyParams = {
            displayName: "Weekly meeting reminder",
            body: {
              text: "Please update your slides before the meeting."
          }
    }
    var resp = await platform.post(endpoint, bodyParams)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  } catch(e) {
    console.log("Unable to create a user SMS template.", e.message)
  }
}

/*
  List personal reusable SMS templates
*/
async function list_user_sms_template(){
  try {
    let endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates"
    var resp = await platform.get(endpoint)
    var jsonObj = await resp.json()
    console.log(jsonObj)
    for (var record of jsonObj.records){
      console.log(record)
    }
  } catch(e) {
    console.log("Unable to list user SMS templates.", e.message)
  }
}

Python

import json
from ringcentral import SDK

#
# Create a personal reusable SMS template
#
def create_user_sms_template():
    try:
        bodyParams = {
            'displayName': "Weekly meeting reminder",
            'body': { 'text': "Please update your slides before the meeting." }
        }
        endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates"
        resp = platform.post(endpoint, bodyParams)
        jsonObj = resp.json_dict()
        print(json.dumps(jsonObj, indent=2, sort_keys=True))
    except Exception as e:
        print ("Unable to create a user SMS template. " + str(e))


#
# List personal reusable SMS templates
#
def list_user_sms_template():
  try:
      endpoint =  "/restapi/v1.0/account/~/extension/~/message-store-templates"
      resp = platform.get(endpoint)
      jsonObj = resp.json_dict()
      print(json.dumps(jsonObj, indent=2, sort_keys=True))
  except Exception as e:
      print ("Unable to list user SMS templates. " + str(e))

# Authenticate a user using a personal JWT token
def login():
    try:
      platform.login( jwt= "RC_USER_JWT" )
      create_user_sms_template()
    except Exception as e:
      print ("Unable to authenticate to platform. Check credentials. " + str(e))

# Instantiate the SDK and get the platform instance
rcsdk = SDK("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com")
platform = rcsdk.platform()

login()

PHP

<?php
require('vendor/autoload.php');

// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" );
$platform = $rcsdk->platform();

/* Authenticate a user using a personal JWT token */
try {
  $platform->login(["jwt" => "RC_USER_JWT"]);
}catch (\RingCentral\SDK\Http\ApiException $e) {
  // Getting error messages using PHP native interface
  print 'Expected HTTP Error: ' . $e;
  exit ("Error message: " . $e->apiResponse->response()->error() . PHP_EOL;
}
create_user_sms_template();

/*
  Create a personal reusable SMS template
*/
function create_user_sms_template(){
  global $platform;
  try {
    $bodyParams = array(
      'displayName' => "Weekly meeting reminder",
      'body' => array(
        'text' => "Please update your slides before the meeting."
        )
    );
    $endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates";
    $resp = $platform->post($endpoint, $bodyParams);
    $jsonObj = $resp->json();
    print_r (json_encode($jsonObj, JSON_PRETTY_PRINT) . PHP_EOL);
  } catch (\RingCentral\SDK\Http\ApiException $e) {
    exit("Unable to create a user SMS template. " . $e->getMessage() . PHP_EOL);
  }
}

/*
  List personal reusable SMS templates
*/
function list_user_sms_template() {
  global $platform;
  try {
    $endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates";
    $resp = $platform->get($endpoint);
    $jsonObj = $resp->json();
    print_r (json_encode($jsonObj, JSON_PRETTY_PRINT) . PHP_EOL);
  } catch (\RingCentral\SDK\Http\ApiException $e) {
    exit("Unable to list user SMS templates. " . $e->getMessage() . PHP_EOL);
  }
}
?>

Ruby

require 'ringcentral'

#
# Create a personal reusable SMS template
#
def create_user_sms_template()
  begin
    bodyParams = {
        'displayName': "Weekly meeting reminder",
        'body': { 'text': "Please update your slides before the meeting." }
    }
    endpoint = "/restapi/v1.0/account/~/extension/~/message-store-templates"
    resp = $platform.post(endpoint, payload: bodyParams)
    puts JSON.pretty_generate(JSON.parse(resp.body.to_json))
  rescue StandardError => e
    puts ("Unable to create a user SMS template." + e.to_s)
  end
end

#
# List personal reusable SMS templates
#
def list_user_sms_template()
  begin
    endpoint =  "/restapi/v1.0/account/~/extension/~/message-store-templates"
    resp = $platform.get(endpoint)
    puts JSON.pretty_generate(JSON.parse(resp.body.to_json))
  rescue StandardError => e
    puts ("Unable to list user SMS templates." + e.to_s)
  end
end

# Authenticate a user using a personal JWT token
def login()
  begin
    $platform.authorize( jwt: "RC_USER_JWT" )
    create_user_sms_template()
  rescue StandardError => e
    puts ("Unable to authenticate to platform. Check credentials." + e.to_s)
  end
end

# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" )

login()

using System;
using System.Threading.Tasks;
using RingCentral;

namespace User_SMS_Templates
{
  class Program
  {
    static RestClient restClient;

    static async Task Main(string[] args)
    {
      try
      {
        // Instantiate the SDK
        restClient = new RestClient( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");

        // Authenticate a user using a personal JWT token
        await restClient.Authorize("RC_USER_JWT");
        await create_user_sms_template();
      }
      catch (Exception ex)
      {
        Console.WriteLine(ex.Message);
      }
    }
    /*
    Create a personal reusable SMS template
    */
    static private async Task create_user_sms_template()
    {
      try
      {
        var bodyParams = new MessageTemplateRequest();
        bodyParams.displayName = "Weekly meeting reminder";
        bodyParams.body = new TemplateInfo() { text = "Please update your slides before the meeting." };
        var resp = await restClient.Restapi().Account().Extension().MessageStoreTemplates().Post(bodyParams);
        Console.WriteLine(JsonConvert.SerializeObject(resp));
      }
      catch (Exception ex)
      {
        Console.WriteLine("Unable to create a user SMS template. " + ex.Message);
      }
    }
    /*
    List personal reusable SMS templates
    */
    static private async Task list_user_sms_template()
    {
      try
      {
        var queryParams = new ListUserMessageTemplatesParameters();
        queryParams.scope = "Personal";
        var resp = await restClient.Restapi().Account().Extension().MessageStoreTemplates().List(queryParams);
        foreach (var record in resp.records)
        {
          Console.WriteLine(JsonConvert.SerializeObject(record));
        }
      }
      catch (Exception ex)
      {
        Console.WriteLine("Unable to list user SMS templates. " + ex.Message);
      }
    }
  }
}

Java

package User_SMS_Templates;

import java.io.IOException;
import com.google.common.reflect.TypeToken;
import com.google.gson.Gson;

import com.ringcentral.*;
import com.ringcentral.definitions.*;

public class User_SMS_Templates {
  static RestClient restClient;

  public static void main(String[] args) {
    // Instantiate the SDK
    restClient = new RestClient( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");
    var obj = new User_SMS_Templates();
    try {
      // Authenticate a user using a personal JWT token
      restClient.authorize( "RC_USER_JWT" );
      obj.create_user_sms_template();
    } catch (RestException | IOException e) {
      e.printStackTrace();
    }
  }

  /*
  Create a personal reusable SMS template
  */
  private void create_user_sms_template()  throws RestException, IOException {
    try {
      var bodyParams = new MessageTemplateRequest();
      bodyParams.displayName = "Weekly meeting reminder";
      bodyParams.body = new TemplateInfo();
      bodyParams.body.text = "Please update your slides before the meeting.";
      var resp = restClient.restapi().account().extension().messageStoreTemplates().post(bodyParams);
      String jsonStr = new Gson().toJson(resp, new TypeToken<Object>(){}.getType());
      System.out.println(jsonStr);
    }catch(RestException e) {
      System.out.println(e.getMessage());
    }
  }

  /*
  * List personal reusable SMS templates
  */
  private void list_user_sms_templates()  throws RestException, IOException {
    try {
      var queryParams = new ListUserMessageTemplatesParameters();
      queryParams.scope = "Personal";
      var resp = restClient.restapi().account().extension().messageStoreTemplates().list(queryParams);
      for (var record : resp.records) {
        String jsonStr = new Gson().toJson(record, new TypeToken<Object>(){}.getType());
        System.out.println(jsonStr);
      }
    }catch(RestException e) {
      System.out.println(e.getMessage());
    }
  }
}