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.
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:
Mobile Originated Message — a user can text you a keyword that explicitly opts them in to your sender’s audience.
The SMS channel registration API — you can register individual channels. This may be helpful if your audience opts in to SMS messages from your app or website.
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. — you can register users in bulk and send them a message at the same time.
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"
}
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 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
.
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"
}
{
"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,
"device_attributes": {
"ua_ndc": "503",
"ua_subdivision": "US-OR"
},
"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 anmsisdn
that is newer than anopted_out
value on the channel. This does not update theopted_in
value on the channel; it only overrides theopted_out
value to send the current message. You must update theopted_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.
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
examplePOST /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.
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.
opted_in
value for a channelPUT /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.
POST /api/sms/15035556789/keywords HTTP/1.1
Content-Type: application/json
Authorization: Basic <master authorization string>
{
"keyword" : "stop",
"sender_ids" : [ "US:54321", "1234"]
}