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 using the API.

This page explains how to send messages using the API. If you want to send an SMS message through the Airship dashboard, see the SMS Notification Tutorial.

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

Airship can shorten links in your SMS messages, saving valuable characters for your message and helping you track engagement with your SMS messages. When you enable link shortening, Airship replaces your URL with unique, shortened URLs for each member of your audience. You can use custom domains for your shorten links, e.g., mysite.co, or use the default airsp.co or airsp.eu domains. Contact Airship if you want to use a custom domain for shortened links. To support a custom domain, you must configure your web server appropriately.

Shortened URLs:

  • Reduce the total number of characters in your messages. Shortened links using the default airsp domains consume exactly 25 characters.
  • Track engagement with SMS messages. Airship generates short_link_click events in the Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. (RTDS), and generates engagement reports based on short-link usage to help you track the effectiveness of your messages and engagement down to individual audience members.
  • Support adding or removing tags from your audience when they tap or click a link by adding query parameters to your URL — ?ua-tag-add=tag_group:tag or ?ua-tag-remove=tag_group:tag.
  • Expire 60 days after they are sent.

For Airship to recognize and shorten your links, your URLs must:

  • Begin with http:// or https://.
  • Begin and end with a space. Your URL cannot have beginning or trailing punctuation or space characters in the URL; spaces determine the beginning and end of the URL.

To shorten links in your message:

  • In the Dashboard: Check the box to shorten links when writing a message. You can also set a default link shortening setting in *Settings » Configurations » Feature Settings*.
     Note

    Your project’s link shortening setting does not affect operations in the API; you must set "shorten_links": true to shorten links in messages you send using the Airship API. See the SMS Object for more information.

  • In the API: add the shorten_links boolean to your payload.
    <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-http" data-lang="http"><span style="color:#960050;background-color:#1e0010">    </span><span style="color:#a6e22e">POST</span> /api/templates/push <span style="color:#66d9ef">HTTP</span><span style="color:#f92672">/</span><span style="color:#ae81ff">1.1</span>
    <span style="color:#ae81ff">Authorization: Basic &lt;master authorization string&gt;</span>
    <span style="color:#ae81ff">Accept: application/vnd.urbanairship+json; version=3;</span>
    <span style="color:#ae81ff">Content-Type: application/json</span>
    
    {
        &#34;audience&#34;: {
        &#34;named_user&#34;: &#34;user&#34;
        },
        &#34;notification&#34;: {
        &#34;sms&#34;: {
            &#34;alert&#34;: &#34;An alert with a link for SMS users https://www.mysite.com/long_url?ua-tag-add=my_tag_group:cool_tag&#34;,
            &#34;expiry&#34;: 172800,
            &#34;shorten_links&#34;: true
        }
        },
        &#34;device_types&#34;: [ &#34;sms&#34; ]
    }
    </code></pre></div>
    
 Note

You may not want to use shortened links for static, easily recognizable URLs, e.g, links to your terms and conditions. If you want to use a persistent shortened link like https://yoursite.com/help, you must provide the URL yourself. You can enable or disable link shortening whenever you send a message from the Airship dashboard.

Tag Actions with Shortened Links

You can add or remove tags from users who engage with shortened links in your SMS messages by adding query parameters to your URLs. Shortened links with tag actions are the same length as URLs without, making it easy to track engagement with your users. You can also use tag change events to kick off automation rules or journeys, making it easier to integrate SMS messaging campaigns into your larger messaging strategy.

  • Add a tag: ?ua-tag-add=my_tag_group:tag_to_add
  • Remove a tag: ?ua-tag-remove=my_tag_group:tag_to_remove

You can perform up to 100 total tag actions (add and remove) per SMS message.

The following payload is a simple example in which Airship would apply the blazers tag and remove the no_preference tag in the fav_team tag group for anybody who engages with the link.

Add and Remove a tag in an SMS Notification
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "audience": {
      "AND": [
         {
            "tag": "basketball",
            "group": "interests"
         },
         {
            "tag": "portland",
            "group" "metro_area"
         }
      ]
   },
   "notification": {
      "sms": {
         "alert": "Vote for the Blazers as your favorite team! https://www.mysite.com/long_url?ua-tag-add=fav_team:blazers&ua-tag-remove=fav_team:no_preference",
         "expiry": 172800,
         "shorten_links": true
      }
   },
   "device_types": [ "sms" ]
}

Personalization Templates

You can take advantage of SMS templates when using the /create-and-send API or when using the /pipelines API to send an automated message.

Example Request: Send an SMS using a template created in the Airship UI
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2018-08-30T22:35:00",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver",
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms" : {
      "template" : {
        "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
      }
    }
  }
}

Example Request: Send an SMS using an inline template
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
  "audience": {
    "create_and_send" : [
      {
        "ua_sender" : "12345",
        "ua_msisdn" : "15558675309",
        "ua_opted_in" : "2018-08-30T22:35:00",
        "customer": {
            "first_name": "Jenny",
            "last_name": "Smith",
            "location": "Vancouver",
        },
        "cart" : [
          {
            "name" : "Rubber Gloves",
            "code" : "abaccgdsagsde",
            "qty": 1
          },
          {
            "name" : "Bleach Alternative",
            "code" : "cacadgdesgaga",
            "qty": 1
          }
        ]
      }
    ]
  },
  "device_types" : [ "sms" ],
  "notification" : {
    "sms" : {
      "template" : {
        "fields" : {
          "alert" : "Hi, {{customer.first_name}}, your {{#each cart}}{{this.name}}{{/each}} are ready to pickup at our {{customer.location}} location!"
        }
      }
    }
  },
  "campaigns" : {
    "categories" : [ "order-pickup" ]
  }
}