Getting Started

When working with SMS, you must register each audience member’s MSISDNThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. with a sender using the Channels API or a keyword operation. Registering an SMS channel returns a channel_id. If the audience member did not explicitly opt in to notifications when they register, you’ll trigger a double opt-in process.

This document explains the registration processes for SMS channels.

See the SMS Channels API reference for more information about SMS channel endpoints.

Configure Your Project

Contact Airship to set up your sendersThe 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. , provision your project for SMS notifications, and enable keywords.

 Important

Procuring or migrating an existing sender code is not instantaneous. Short code migrations may require up to 8 weeks of lead time.

Register SMS Users

The process to register users can depend on local data privacy laws and whether or not your audience explicitly opts in to notifications.

There are three ways to register users:

Users explicitly opting into notifications using a keyword trigger an opt in flow. Airship defaults to a double opt-in, but it is common to use a single opt-in flow for keyword purposes.

If your user does not explicitly opt into notifications, or provides you their msisdn without using a keyword (through a sign up on your website, in your app, etc.), you will trigger a double opt-in by registering the user through the channel registration API without an opted_in value.

If you register a member of your audience using the channel registration API with an opted_in value, the user will not receive a notification confirming that they opted in.

graph TD A[User provides
MSISDN] -->B{Did user
explicitly opt in?} B -->|No| C[Create channel] B --> |Yes, with keyword| D[Create channel] B --> |"Yes, without keyword
(Register through API)"| Z[Create channel] subgraph Single Opt-in D end C -->|Send MSISDN MT opt-in request| E{Did user respond
with opt-in keyword?} E -->|Yes| F[Update channel with opt-in] E -->|No| G[User cannot receive messages] F --> |Send user confirmation| H[User can receive messages] D -->|Send user confirmation| H Z --> H subgraph Double Opt-in C E F G end subgraph Silent Opt-in Z end

SMS Channel Registration API

You can use the SMS channel registration API to register SMS users when they opt in to SMS notifications through your website or app.

Users register and opt in to messages from particular senders, so Airship generates a unique channel_id for each msisdn/sender combination.

You can also create channels that are not opted in to notifications, triggering a double opt-in flow. You might do this when offering shipping notifications or event updates to users who have opted in to different notifications from you.

If you do not provide an opted_in date when registering a new user, Airship starts a double opt-in process and sends an message to the MSISDN, asking the user to respond with a keyword to initiate the opt-in process, followed by a second message to text “Y” (or “y”) to complete the opt-in. You cannot send a message to a user until you update their channel with a valid opted_in value.

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": "US: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 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 dashboard, 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": [
         "US:12345"
      ],
      "timezone": [
         "America/Los_Angeles"
      ],
      "ua_locale_country": [
         "US"
      ],
      "named_user_id": [
         "cool_person"
      ],
      "ua_locale_language": [
         "en"
      ],
      "ua_opt_in": [
         "true"
      ]
   }
}

Send a Message While Registering Users

If your audience provides you their MSISDNs, you can register them with Airship and send them a message at the same time using the Create and Send API or an Inline ListAn ad-hoc, CSV-formatted list of email, SMS, or open channel addresses that you want to register and/or send a message to. Unlike static lists or segments, you upload this list when creating your message; Airship registers new addresses in the list as channels when you send your message. .

If you provide a ua_opted_in value for the new channels in your audience, they will be eligible to receive future messages. If you do not set a ua_opted_in value for the new channels, they’ll receive the message and begin the double opt-in flow.

Addresses in the list that are already registered with Airship will receive your message if either of the following conditions are true:

  • They are already opted in for messaging (their channel has a valid opted_in value).
  • You provide a ua_opted_in date-time value for an msisdn that is newer than an opted_out value on the channel. This does not update the opted_in value on the channel; it only overrides the opted_out value to send the current message. You must update the opted_in value using SMS channel update API to opt it back into your messaging audience.

Your inline list must include msisdn, sender and ua_opted_in headings. You can use additional headings to personalize messages with HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. . See: Inline List CSV Format and Inline List Object and Array Notation.

Example inline list CSV
msisdn,sms_sender,ua_opted_in,fav_food
5558675309,US:12345,2020-05-05T10:34:22,tacos
5559867543,US:12345,2020-05-05T12:03:45,pizza

/create-and-send example
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": [
            {
                "msisdn": "5558675309",
                "sender": "US:12345",
                "opted_in": "2020-05-05T10:34:22",
                "fav_food": "tacos"
            },
            {
                "msisdn": "5551234567",
                "sender": "US:12345",
                "opted_in": "2020-05-05T12:03:45",
                "fav_food": "pizza"
            }
        ]
    },
    "device_types": [
        "sms"
    ],
    "notification": {
        "sms": {
            "template": {
                "fields": {
                    "alert": "Hey, I hear you like {{fav_food}}"
                }
            }
        }
    }
}

Update Opt-in Status

If your audience opts in to messaging outside of a standard opt-in flow — through your website or app — you can update the channel’s opted_in value to add them to your messaging audience.

You can also update a channel to change its time zone and locale information.

 Note

You must know the channel_id to update a channel. You can look up a channel by msisdn and sender combination to find the channel identifier that you want to update.

Update the opted_in value for a channel
PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

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

Manually Trigger Keyword Interactions

You can trigger a keyword interaction on behalf of your audience, without receiving a mobile originated (MO) message, using the Airship API. You may want to do this to test your keywords or to trigger keyword interactions on behalf of your audience — including keywords that opt users in or out of your messaging audience.

For example, if a member of your audience requests to be removed from your messaging audience over the phone, you could use the following operation to opt them out. This triggers the mobile terminated message confirming that the user has been removed from your messaging audience.

Trigger a “STOP” Keyword Interaction
POST /api/sms/15035556789/keywords HTTP/1.1
Content-Type: application/json
Authorization: Basic <master authorization string>

{
   "keyword" : "stop",
   "sender_ids" : [ "US:54321", "1234"]
}