SMS Notifications

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

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.

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": "Airship",
         "sender_address": "no-reply@airship.com",
         "reply_to": "no-reply@airship.com"
      }
   },
   "device_types": [
      "android",
      "sms",
      "web",
      "email"
   ]
}

Schedule an SMS Message

If you don’t set an SMS channel’s timezone when you register a channel, Airship will attempt to infer the channel’s time zone from its msisdn. You can use time zones to schedule messages at a particular time relative to your audience’s different time zones.

Example Request: Send an SMS in your Audience's local time
POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "schedule": { 
      "local_scheduled_time": "2020-03-20T09:15:00"
   },
   "name": "SMS At Local Time",
   "push": {
      "audience": { 
         "tag": "likes_baseball" 
      },
      "device_types": "sms",
      "notification": { 
         "alert": "Are you ready for baseball season? Get geared up for opening day at https://www.sportstuff.com/baseball/opening_day_deals/",
         "sms": {
            "alert": "Are you ready for baseball season? Get geared up for opening day at https://www.sportstuff.com/baseball/opening_day_deals/",
            "shorten_links": true
         } 
      }
   }
}

Personalization Templates

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 below, 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.
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"
      }
   }
}

Dashboard

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