Getting Started

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 MSISDNThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. with 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.

Resources

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

Configure Your Project

Configuration requires setup of your Sender IDThe alphanumeric code that your SMS messages come from — like a phone number or name. Your audience subscribes to each individual sender ID they want to receive messages from. . Contact Airship Support or Sales 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 SMS Users

Use the SMS channel registration API to register SMS users. Users register and opt in to messages from particular senders, so Airship generates a unique channel_id for each msisdn / sender combination.

If you do not provide an opted_in date when registering a user, Airship 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. You cannot send a message to a user until an opted_in value is set on their channel.

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

Determining Time Zone and Locale for SMS Channels

When you register or update an SMS user in Airship, you can set their IANA timezone, locale_country, and locale_language. If you don’t set these values yourself, Airship attempts to infer country and time zone information from the country code and format of your audience’s phone numbers (MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. ). You can use this information to reach your SMS audience at the right time and in the right language.

 Note

Airship does not infer locale_language values.

Airship takes advantage of the timezone when you use schedule a message using local_scheduled_time in the API or the Delivery By Time ZoneAn option for scheduled messages that delivers the messages according to recipient device’s current time zone. checkbox in the Delivery step in the Airship UI, and sends your message to your audience at the specified time in their respective time zones.

The locale_country and locale_language values support localization. If you send a localized message, Airship sends your audience the appropriate version of your message based on their country or the combination of country and language values.

These values all appear in an SMS channel’s tag_groups.

Example SMS Registration

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

{
  "msisdn" : "15035556789",
  "sender": "12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}

Example SMS Channel Object
{
   "channel_id": "a1308318-80c9-43ca-b47e-7e97d2cb6f4a",
   "device_type": "sms",
   "installed": true,
   "opt_in": true,
   "push_address": null,
   "created": "2019-05-24T20:39:46",
   "last_registration": "2020-02-11T19:32:06",
   "alias": null,
   "tags": [],
   "tag_groups": {
      "ua_channel_type": [
         "sms"
      ],
      "ua_sender_id": [
         "12345"
      ],
      "timezone": [
         "America/Los_Angeles"
      ],
      "ua_locale_country": [
         "US"
      ],
      "named_user_id": [
         "cool_person"
      ],
      "ua_locale_language": [
         "en"
      ],
      "ua_opt_in": [
         "true"
      ]
   }
}