Use SMS Templates

Why would one use a template for SMS messages sent via the TMS API? One reason is to separate your content creation and approvals from the act of sending the message.

Separation of concerns is great for business processes, and great for performance. Using SMS Templates, the body of SMS messages can be defined and updated in the TMS API, instead of in your application code.

simplifies your content update process
reduces the bandwidth required for your application to send SMS messages
changes to SMS contents can be made without any application code changes

Now, sending an SMS message that uses a template can be as simple as specifying which template to use and who should receive it.

In this tutorial, we’ll cover how to create an SMS template, how to use a template when sending new SMS messages, and how to update a template.

If you have not yet sent an SMS message using TMS, you should first look at the /templates/sms and /messages/sms endpoint reference documents for more information on how to create, update, and use your SMS templates.

Prerequisites

Before you can send an SMS message, there are a few things your organization will need to do to enable the Targeted Messaging Service:

Purchase the Targeted Messaging Service
Configure SMS addresses for the Targeted Messaging Service
Get a Targeted Messaging Service API Token

To get started on any of these, please SMS support@granicus.com.

Create an SMS Template

To start off, let’s create a template for new user confirmation SMS messages that includes a way to provide a new user with their unique confirmation URL. Just like when we send a regular SMS message, the first thing we need to do is decide what we want to send. Let’s create a template that includes the following body:

You have subscribed to Snow Emergency Alerts.  Reply STOP to unsubscribe.

Now that we know what we want to send, it’s simply a matter of making a POST to /templates/sms and specifying a body.

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/templates/sms --data \
'{
     "body": "You have subscribed to receive Snow Emergency Alerts.  Reply STOP to unsubscribe.",
     "uuid": "new_template"
}'

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
template_body = <<eob
Thank you for signing up to receive snow alert SMS.
eob

template = client.sms_templates.build(body: template_body, uuid: "new_template")
template.post
=> true

Once this POST is sent, TMS will respond with your newly created template object, which you will need for the next step.

Send an SMS Message Using a Template

With our template now defined and ready, we can now use it to send a confirmation SMS simply by creating a new SMS message and specifying the template and our recipients:

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/sms --data \
'{
  "recipients": [
    { 
      "phone": "6515551000"
    }, 
    {  
      "phone": "(651) 555-1001"
    }
  ], 
  "_links": {
    "sms_template": "new_template"
  }
}'

// RESPONSE BODY
{
  "id":"10020",
  "uuid":"new_template",
  "body": "You have subscribed to receive Snow Emergency Alerts.  Reply STOP to unsubscribe.",
  "created_at": "2015-10-23T19:06:09Z",
  "status": "new",
  "_links": {
      "self": "/messages/sms/10020",
      "recipients": "/messages/sms/10020/recipients",
      "failed": "/messages/sms/10020/recipients/failed",
      "sent": "/messages/sms/10020/recipients/sent"
  }
}

sms = client.sms_messages.build
sms.links[:sms_template] = template.uuid
sms.recipients.build(sms:'6155551000')
sms.recipients.build(sms:'6155551111')
sms.recipients.build(sms:'6155552222')
sms.post
=> true

When you use an SMS template to create a new SMS message, your new SMS message will take on the values that are set in the template. In this case, our new SMS took on the body value, so we did not have to specify that while creating the message.

Update an SMS Template

Change comes to all things, including your templates. Let’s update our user confirmation SMS template to add a HELP option:

You have subscribed to Snow Emergency Alerts.  Reply STOP to unsubscribe.
Reply HELP for more options.

Fortunately, updating the content of your template is as easy as issuing a PUT:

curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/sms/new_template --data \
'{
     "body": "You have subscribed to receive Snow Emergency Alerts. Reply STOP to unsubscribe. Reply HELP for assistance"
}'

new_template_body = <<eob
You have subscribed to receive Snow Emergency Alerts. Reply STOP to unsubscribe. Reply HELP for assistance
eob

template.body = new_template_body
template.put
=> true

Summary Code Example

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/templates/sms --data \
'{
     "body": "You have subscribed to receive Snow Emergency Alerts.  Reply STOP to unsubscribe.",
     "uuid": "new_template"
}'
curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/sms --data \
'{
  "recipients": [
    { 
      "phone": "6515551000"
    }, 
    {  
      "phone": "(651) 555-1001"
    }
  ], 
  "_links": {
    "sms_template": "new_template"
  }
}'

// RESPONSE BODY
{
  "id":"10020",
  "uuid":"new_template",
  "body": "You have subscribed to receive Snow Emergency Alerts.  Reply STOP to unsubscribe.",
  "created_at": "2015-10-23T19:06:09Z",
  "status": "new",
  "_links": {
      "self": "/messages/sms/10020",
      "recipients": "/messages/sms/10020/recipients",
      "failed": "/messages/sms/10020/recipients/failed",
      "sent": "/messages/sms/10020/recipients/sent"
  }
}
curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/sms/new_template --data \
'{
     "body": "You have subscribed to receive Snow Emergency Alerts. Reply STOP to unsubscribe. Reply HELP for assistance"
}'

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
template_body = <<eob
Thank you for signing up to receive snow alert SMS.
eob

template = client.sms_templates.build(body: template_body, uuid: "new_template")
template.post
=> true
sms = client.sms_messages.build
sms.links[:sms_template] = template.uuid
sms.recipients.build(sms:'6155551000')
sms.recipients.build(sms:'6155551111')
sms.recipients.build(sms:'6155552222')
sms.post
=> true
new_template_body = <<eob
You have subscribed to receive Snow Emergency Alerts. Reply STOP to unsubscribe. Reply HELP for assistance
eob

template.body = new_template_body
template.put
=> true

Overview

Tutorials