SMS

Unlike with our app and web channels, SMS Channel IDs are not generated for you via an installed SDK. Rather, as with Email and Open Channels, you must register the delivery address with a valid MSISDN (phone number) with Urban Airship via our Channels API, which will return a channel_id, or have the delivery address opt into a 2 way long code by performing a double opt-in.

This document explains how to register SMS channels, set up SMS notification templates, and send SMS using either the templates via our personalization API or directly via the push API.

Getting Started

Configure Your Project

Configuration requires setup of your Sender ID (long or short code). Contact Urban Airship Support or your Account Manager to provision your project for SMS notifications and complete the configuration.

Important

Procuring or migrating an existing code is not instant and will require up to 8 weeks of lead time for short codes.

Register users

Once your project is enabled for SMS notifications, you can begin creating Urban Airship SMS channel IDs for your users. You can then send to SMS just as you would for any other notification channel, e.g., iOS, Web. Additionally, you can send directly to a registered MSISDN via our API.

SMS Channel Registration API

Example Request:

POST /api/channels/sms HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
    "msisdn" : "15558675309",
    "sender": "12345",
    "opted_in": "2018-07-10T11:59:59"
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3;
Location: https://go.urbanairship.com/api/channels/34b3dfc1-d717-40fe-89e8-10584ed1c123df6a6b50-9843-0304-d5a5-743f246a4946

{
    "ok": true,
    "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}

To register an SMS channel on demand during your customer workflow, use the SMS Channels registration API.

For compliance reasons you must submit a valid opt-in date with the registration call. If a valid date is not set, we will employ a double opt-in and send an alert to the MSISDN asking the user to text "join" to initiate the opt in process, followed by a message to text "Y" (or "y") to complete the opt-in.

Targeting

Target SMS devices as you would any other supported channel, using audience selectors. Below are a handful of examples targeting SMS channels via different segmentation tools.

Tags

Example Request: Add tag to SMS channel using tag groups

POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
   "audience": {
      "channel": "34b3dfc1-d717-40fe-89e8-10584ed1c123"
   },
   "add": {
      "fish_numbers": [
         "one",
         "two"
      ],
      "fish_colors": [
         "red",
         "blue"
      ]
   }
}

Example Request: Send to SMS using your new tag

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "tag": "blue",
      "group": "fish_colors"
   },
   "notification": {
      "alert": "This one has a little star."
   },
   "device_types": [
      "sms"
   ]
}

When setting tags on an SMS channel, use the Channel Tags endpoint.

In the provided examples, we will first add a new tag to our SMS channel using tag groups, then send a push to an audience defined by channels containing the new tag with the device type sms.

Named Users

Example Request: Associate Named User with SMS channel

POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "channel_id": "adc9465c-68d6-481e-b5b4-6ab5a185b35f",
   "named_user_id": "erika_mustermann"
}

Example Request: Send to SMS using your new tag

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "named_user": "erika_mustermann"
   },
   "notification": {
      "alert": "Test SMS to Named User"
   },
   "device_types": [
      "sms"
   ]
}

Named Users let you associate an ID of your choosing with a single user who is opted in across multiple engagement channels. Typically a Named User ID is an internal identifier in your CRM system.

Associate Named Users with individual SMS channels using the Named Users API.

In the provided examples, we take our new channel and associate it with a named user, then use the Push API to deliver the SMS alert.

Test Groups

Make testing easy by creating Test Groups for use in the Message Composer. Add your SMS channels for testing in the Test Group UI.

Audience Lists

Upload lists of Named Users or SMS channels via the Static Lists API or in the dashboard and use those for targeting through the Push API or Message Composer.

Send to SMS

After your project has been provisioned for SMS notifications and you have successfully registered MSISDNs for your users, you can send SMS messages via the following methods:

Push API

Example Request: Send to a single MSISDN

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "sms_id": {
         "sender": "12345",
         "msisdn": "15031112222"
      }
   },
   "device_types": [
      "sms"
   ],
   "notification": {
      "alert": "Hi MSISDN"
   }
}

Example Request: Send to multiple registered channels using a Named User

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "named_user": "omnichannel_man"
   },
   "notification": {
      "alert": "Default message, will only go to web channels in this example.",
      "android": {
        "alert": "Message for Android devices."
      },
      "sms": {
         "alert": "Alert text for SMS."
      },
      "email": {
         "subject": "Omnichannel Test",
         "html_body": "<h1>Greetings!</h1><p>Email paragraph text.</p>",
         "plaintext_body": "Email paragraph text, plaintext version.",
         "message_type": "transactional",
         "sender_name": "Urban Airship",
         "sender_address": "no-reply@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com"
      }
   },
   "device_types": [
      "android",
      "sms",
      "web",
      "email"
   ]
}

Send SMS notifications to SMS channels alone, or combine them with other message types and platforms, e.g., iOS and Web, using our Push API.

Personalization Templates

Example Request: Create a template with a variable for FIRST_NAME

POST /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
    "name": "Test SMS template",
    "description": "Testing an SMS personalization template",
    "variables": [
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}}, this is your test SMS welcome message!"
        }
    }
}

Example Response Get your template ID:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
}

Example Request: Send SMS to template with substitution

POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "sms"
   ],
   "merge_data": {
      "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
      "substitutions": {
         "FIRST_NAME": "Jane"
      }
   }
}

In some cases, you will create a template for your SMS notifications. Follow the Message Personalization Tutorial to learn how to create a template via the UI.

You can also create a template via the Personalization API.

In the examples to the right, we will:

  1. Create a simple template with a variable for first name, using the Create Template API.
  2. Retrieve the template ID in the response.
  3. Send an SMS notification to a named user, using the Push to Template API and providing the substitution for the user's first name in the FIRST_NAME field.

Dashboard

Send an SMS notification via the Message workflow. Follow the steps in the SMS Notification Tutorial.

Reporting & Analytics

Sends from Urban Airship systems are counted per message. Reporting on sends is available in individual Message Reports, as well as in the Connect stream, and Insight analytics.

Opt in and Opt out events are shown in the Engage Devices report.

Resources

See the SMS Channels API reference for more information on all the SMS endpoints.