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"
   ]
}

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.