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 IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address. . 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 Sales  to:

1. Provision your project for SMS notifications.
2. Set up your sender IDs.

Your project can have multiple senders, and your audience can opt in to multiple senders within your project.

If your Airship project has more than one sender ID, you can select one when you create your message. Selecting an individual sender ID ensures that your message only goes to members of your audience subscribed to that sender.

When your sender ID is a short code, prepend the 2-letter ISO 3166 country code  when using the short code in the API. This is similar to the way that you would prepend a country code to a standard phone number.

Set Up Keywords

You can set up keywords in the Airship dashboard. See: SMS keywords.

Register SMS Users

After Airship completes your project setup, you can 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 multiple ways to register users:

• Mobile-originated message — A user can text you a keyword that explicitly opts them in to your sender’s audience.
• Opt-in form — A user can sign up for SMS messages through an opt-in form you can add to your website.
• SMS channel registration API — Use the SMS channel registration API to register individual channels. This may be helpful if your audience opts into SMS messages from your app or website.
• Bulk registration when sending a message — This can be done using the Create and Send API or the Upload users option in the Message composer. See: 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. and Create and Send API.
• SDK — Register an SMS channel through the Mobile SDKs.
• CSV Upload — You can upload MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. in a CSV file to set TagsMetadata that you can associate with channels or named users for audience segmentation. Generally, they are descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast or weather_alerts_los_angeles. Tags are case-sensitive. or AttributesMetadata that you can use for audience segmentation. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. . Airship registers new channels for MSISDN/sender combinations that are new to your project. See:
  • Setting attributes using a CSV file
  • Setting tags using a CSV file

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.

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.

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

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

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. In the dashboard, you can do this using the Upload users option in the Message composer.

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 ua_msisdn, ua_sender and ua_opted_in headings. You can use additional headings to personalize messages with HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data. . See: Inline lists: Formatting your list.

ua_msisdn,ua_sender,ua_opted_in,fav_food
5558675309,US:12345,2020-05-05T10:34:22,tacos
5559867543,US:12345,2020-05-05T12:03:45,pizza

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_msisdn": "15558675309",
                "ua_sender": "US:12345",
                "ua_opted_in": "2020-05-05T10:34:22",
                "fav_food": "tacos"
            },
            {
                "ua_msisdn": "15551234567",
                "ua_sender": "US:12345",
                "ua_opted_in": "2020-05-05T12:03:45",
                "fav_food": "pizza"
            }
        ]
    },
    "device_types": [
        "sms"
    ],
    "notification": {
        "sms": {
            "alert": "Hey, I hear you like {{fav_food}}"
        }
    }
}

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.

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.

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

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": "US:12345",
  "opted_in": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}