Sending an SMS

TMS provides a flexible and easy way for your application to push notifications to your users. In this tutorial, we’ll walk through a couple of scenarios for using TMS to send static or customized SMS messages to users.

After this tutorial, be sure to look at the /messages/sms endpoint reference documents for more information on how to view and manage the SMS messages you send via TMS.

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 one or more from numbers for the Targeted Messaging Service
  • Get a Targeted Messaging Service API Token

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

Send a Simple SMS Message to One Person

Once you’ve covered the prerequisites, sending an SMS message is simple. The first thing you need to do is decide who you’re going to SMS, and what you want to say. Let’s send a simple hello to Jim with an SMS message like the following:

Hi!

Now that you know what we want to send, it’s simply a matter of making a POST to /messages/sms with body and recipients specified to what you want. TMS then responds with the JSON below.

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/sms --data \
'{
  "body": "Hi!",
  "recipients": [
    {
      "phone": "6515551212"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 2689564,
  "body": "Hi!",
  "created_at": "2016-06-06T15:22:48Z",
  "status": "new",
  "_links": {
    "self": "/messages/sms/2689564",
    "recipients": "/messages/sms/2689564/recipients",
    "failed": "/messages/sms/2689564/recipients/failed",
    "sent": "/messages/sms/2689564/recipients/sent"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
sms = client.sms_messages.build(body:'Hi!')
sms.recipients.build(phone:'6515551212')
sms.post
=> true

Once this POST is sent, TMS will send your SMS message from the short code or phone number associated with your TMS account.

Send a Simple SMS Message to Multiple People

At some point, you’ll probably want to send an SMS message to more than one person. This is just as simple to do with TMS as sending an SMS message to a single person - all you need to do is specify multiple recipients. Let’s send our hello message again, but this time to a few more people:

$ curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json" https://tms.govdelivery.com/messages/sms --data \
'{
  "body": "Hi!",
  "recipients": [
    {
      "phone": "6515551212"
    },
    {
      "phone": "6125551212"
    },
    {
      "phone": "4158675309"
    }
  ]
}'

// RESPONSE BODY
{
  "id": 2689563,
  "body": "Hi!",
  "created_at": "2016-06-06T15:22:48Z",
  "status": "new",
  "_links": {
    "self": "/messages/sms/2689563",
    "recipients": "/messages/sms/2689563/recipients",
    "failed": "/messages/sms/2689563/recipients/failed",
    "sent": "/messages/sms/2689563/recipients/sent"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
sms = client.sms_messages.build(body:'Hi!')
sms.recipients.build(phone:'6515551212')
sms.recipients.build(phone:'6125551212')
sms.recipients.build(phone:'4158675309')
sms.post
=> true

Again, once this POST is sent, TMS will send your SMS message to every recipient you specify.

In both of our examples, you’ve probably noticed that TMS also sends you a response with a number of properties. Among these properties are a set of URLs (all found in the _links object) that you can request to review the SMS message you sent and check its status, review the status of all of the recipients you specified for your SMS message, and retrieve lists of recipients who have received your SMS message and recipients who TMS could not deliver your SMS message to.

Send an SMS Message Using a Template

You can use templates to send a message:

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 message took on the body value, so we did not have to specify it while creating the message. If the SMS template is not explicitly associated with a from address the SMS message will use properties like from number set at the from address-level.