SMS notifications help you reach a wide audience quickly, without an app or development work. You can send SMS (text) or MMS (image) messages to your audience of opted-in MSISDNs (phone numbers).
Reach: Contact customers who don’t have your app, or re-engage customers
who are inactive on other channels or at-risk.
Personalization: Send transactional messages triggered by a backend
system, e.g., order confirmation and shipment tracking updates.
Mobile wallet
integration: Deliver personalized passes, tickets, coupons, and more.
Integrated platform: Centralize all your engagement channels; manage
personalization, scheduling, and deployment for all message types; and measure
SMS alongside all your other channels, all in the Airship platform.
No app required: If you do have an app, however, SMS notifications are
an additional channel
that you can use to engage your audience. You can decide which channel
(app, SMS, etc.) is more important for different types of messaging, adjust
your messaging for different channels, set priority per channel, and much
more. See
Channel CoordinationA group of strategies you can use to target users where they are most likely to receive your message.
for details about priority channel and other cross-channel engagement
strategies.
Use Cases
Sports Events
Before the event: Last-minute ticket offers, seat upgrades, parking
coupons.
During the event: Coupons, promotions of venue facilities, promotion
of sponsor experiences to increase partner activations.
Mobile wallet pass delivery: Coupons, tickets.
Retail
Campaigns: Location-aware promotions, promotions to drive in-store
traffic, lifecycle marketing.
Transactional: Offer confirmations, order status updates.
Mobile wallet pass delivery: Loyalty card updates, coupons.
Mobile wallet pass delivery: Boarding passes, loyalty card updates, coupons.
Media
Campaigns: Re-engage inactive or at-risk readers.
News: Preferred new categories.
SMS Users in Airship (Sender and MSISDN)
A mobile device is represented by an MSISDN. An MSISDN is the mobile phone number of a device in your Airship audience. While MSISDNs represent devices, in general, you can think of an MSISDN as a person — someone in your audience.
Your messages come from one or more Sender IDs. A sender ID is an alphanumeric code that your audience will see when they receive messages from you; it is essentially the phone number or name that your SMS messages come from. Members of your audience subscribe to each individual sender ID they want to receive messages from. Your sender ID can be a standard phone number, short code, or a set of alpha characters representing your sender, like your company name.
Each MSISDN — or member of your audience — subscribes to the sender IDs they want to receive messages from. If your project has multiple sender IDs, you should take care when sending your message to ensure that you reach the right audience members. Use the sender ID to select your audience, so you can be sure that you reach the right MSISDNs when you send your message.
When using a short code sender in the API, you should provide the country code associated with your shortcode, similar to the way you prefix a phone number with a country code.
SMS Notifications and Sending Methods
SMS notifications are text-based messages. They are viewed in the recipient device’s native SMS client. If your message exceeds the character limitation, it will appear as successive messages to the user.
You can send multi-media messages (MMS) to your SMS audience. MMS messages include a fallback, ensuring that users who can’t view the original MMS message still receive a message that makes sense.
When sending an MMS message, you can provide the URL for your image or upload it to Airship. If you do not upload to Airship, you should use image assets you control and a dedicated media host to prevent delivery errors. Do not use images hosted on a site where others could change or remove the images you want to use in your messages.
MMS messages must be:
.gif, .jpeg, .jpg, or .png format.
Hosted over HTTP or HTTPS (for media not hosted by Airship).
Smaller than 2 MB for .jpeg and .jpg.
Smaller than 1 MB for .png and .gif.
Note
We recommend that you use images 650 KB or smaller to improve deliverability. In general, you should use the smallest possible image size to ensure that your audience receives messages quickly, regardless of connection quality.
SMS Link Shortening
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.
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.
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.
SMS Tag Actions
You can add or remove tags from your SMS audience when they use Airship-shortened links in your messages using query parameters in your un-shortened URL. The Airship user interface makes it easy to add or remove tags whenever your message contains a URL.
At the API level, add the following actions to your URL to perform tag actions:
?ua-tag-add=tag_group:tag to add a tag
?ua-tag-remove=tag_group:tag to remove a tag
Note
This feature requires your links to be shortened through Airship.
Data & Analytics for SMS
Opt in/out counts are included in the
Devices report
and individual
message reports.
Message reports also include send counts and custom events for delivery events
and errors.
These counts are also included in Performance Analytics, and you can open a Real-Time Data Streaming event stream to observe SMS-related events in real time.
SMS Configuration & Requirements
Contact Airship Support or Sales to provision your project for SMS notifications.
Your SMS channel requires a Sender ID. A sender ID is an alphanumeric code that your audience will see when they receive messages from you; it is essentially the phone number or name that your SMS messages come from. Members of your audience subscribe to each individual sender ID they want to receive messages from. Each individual user is represented by their msisdn (phone number) registered to a particular Sender ID.
Set Message Limits for SMS
You can set limits on the number of messages you can send your audience on a particular channel within a time frame, to prevent over-messaging.
If a member of your audience reaches the message limit on a channel within the time period, Airship suppresses any messages they would otherwise receive on that channel for the remainder of the time period.
Go to Settings » Configuration » Message Limits to set message limits for each of your messaging channels.
Opt-In/Out Handling
Users must opt in to receive SMS messages from your Sender ID and can opt out at any time. There are two ways users can opt in or opt out of your SMS audience:
Mobile-Originated (MO) Message: A message originating from the mobile handset can contain a keyword that triggers an opt-in. The opt-in keyword can trigger a single or double opt-in flow.
External Opt In: Users can opt in to SMS messages through your app, website, or other channel. You must register these users through the API.
Note
You can test your inbound webhook and trigger keyword interactions on behalf of your audience, without receiving a mobile originated message, using the Airship API. See the Trigger Keyword Interaction endpoint for more information.
SMS User Time Zone and Locale
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.
A mobile-originated message is a message sent from a member of your audience (originating from the mobile handset of a user) to you. A Keyword is a word that you define to perform an action, like opt-in or audience attribution, when used in a mobile-originated message. You can apply tags to your audience based on the keywords they use, segmenting your audience to send relevant messages based on your audience’s keyword-indicated interests.
Contact Airship Sales to provision keywords and associated tag operations. Airship stores your keywords and associated tag operations. Custom keywords and tag operations for keywords are not available through the dashboard or API.
By default, users can text you any of these words to opt out of notifications: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, ARRET. You can also add additional opt-out keywords; like opt-in keywords, specialized keywords can provide additional data about opt-out behaviors.
Mobile-originated messages are represented as events. Each event records the keywords that your audience uses and additional identifying information. You can use these events to observe opt-in and opt-out trends in Performance Analytics, or to get events directly from Real-Time Data Streaming.
Note
You can test your inbound webhook and trigger keyword interactions on behalf of your audience, without receiving a mobile originated message, using the Airship API. See the Trigger Keyword Interaction endpoint for more information.
Mobile-Originated Single Opt-In
Single opt-in is the process of registering users and considering them opted in when they send you a single message containing a keyword. This method does not require users to confirm that they want to opt in through a second mobile-originated (MO) message.
While a single opt-in is a simple way to register users, it may not always be an optimal opt-in method. Airship mobile-originated opt-in handling defaults to a double opt-in process. Contact Airship if you want to take advantage of a single opt-in workflow.
The response to the keyword is a confirmation text message that provides information about the text program. The message usually:
Confirms that the user has subscribed to an on-going text program.
Provides the number of messages the subscriber can expect to receive.
Informs the subscriber where they can obtain more information and how they can opt-out.
Example:
BrandX: Welcome to the BrandX Info and Alerts Program! Message frequency varies by use. For help, reply HELP. To end, reply, STOP. Msg&DataRatesMayApply.
Mobile-Originated Double Opt-In
Double opt-in requires a user to send you a keyword indicating that they want to receive mobile messages, and a second keyword confirming their choice:
Your audience texts a keyword to trigger the opt-in process.
Airship sends your audience a message requesting confirmation using a keyword.
Your audience texts the confirmation keyword, opting in to your audience.
Because each message in the opt-in workflow supports unique keywords, the double opt-in method provides multiple indices to categorize users as they opt in to your audience; you can add, remove, or replace tags for any of the opt-in messages, ensuring that you precisely segment your audiences and target future messages to the right users.
Non-Mobile Single Opt-In
If users provide consent to receive text messages without a mobile-originated keyword — like through your website or app — you can register them through the API in a single step. Use the /api/channels/sms endpoint with the date-time when the user opted_in.
Tip
It may take up to an hour before you can message new users. If you want to message a new SMS user immediately, you can register new SMS users and send a message simultaneously using the create-and-send API or the Upload Users Audience option to send your SMS message.
When registering your audience without a mobile keyword, it is your responsibility to obtain express written consent from users. If users have not provided sufficient consent, you should perform a double opt-in.
Non-Mobile Double Opt-In
If users provide their phone numbers and express interest in SMS messages through your website or app but do not give sufficient consent to receive SMS messages from a particular sender, you can register them through the Airship API without an opted_in value.
When you register a user through the API without an opted_in value, Airship sends them a message prompting them to opt in. The user must then respond with a valid keyword to opt in to notifications.
Tip
Airship generates a channel_id even when you register users who have not opted in. You can add tags to these channels and associate them with named users before audience members opt in.
sequenceDiagram
Participant Audience
Participant You
Participant Airship
Audience->> You: Registers via webform/app
You->> Airship: Register user through API
Airship->>Airship: Creates channel ID for audience
You-->> Airship: (Optional) add tags to new channel
Airship->> Audience: Sends opt-in request via SMS
Audience->> Airship: Texts opt-in keyword to Airship
note over Audience, Airship: Your audience/channel ID is opted in and can receive messages
When registering your audience without a mobile keyword, it is your responsibility to ensure that your users understand that they are agreeing to receive SMS messages from you and provide express written consent to receive SMS messages from you.
If your Airship project has more than one sender, you can select the appropriate sender ID in the Audience step when sending an SMS message to ensure that you send your message from the right sender ID.
Selecting an individual sender:
Determines the sender that your message comes from.
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.
Note
Payloads without country codes are acceptable only if your project has a single short code for a single country.
Register SMS channel with a short code and country designation
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.
Requests to opt in or out of SMS notifications are handled by
Airship. Our opt-in and opt-out database:
Is segregated from campaign content.
Is encrypted.
For opt-ins and opt-outs that occurred via mobile-originated messages on Airship SMS, Airship stores date/time data for those opt-ins and opt-outs for rolling 4 years.
Creating a One-Click Opt-In Link Using HTML
For mobile websites, you can set up a hyperlink or a button on a page that will open up the device’s messaging app and prepopulate the long or short code and keyword for the SMS opt-in.
Note
This feature will work on most mobile devices as well as a few desktop devices, but is not guaranteed to work on every mobile device model or operating system.
HTML Hyperlink Template:
<ahref="sms://CODE?&body=KEYWORD">Click Here to Opt-In</a>
HTML Hyperlink Example:
<ahref="sms://54321?&body=JOIN">Click Here to Opt-In</a>
Inbound (MO) Message Handling
In addition to standard opt-in and opt-out operations, you can configure a webhook to respond to mobile-originated messages.
Inbound message handling uses an SMS keyword webhook. Airship forwards mobile originated messagesA message sent from a member of your audience (originating from the mobile handset of a user) to you. from your audience to your webhook so you can process requests from your audience and send custom, targeted responses to individual members of your audience based on the keywords they use in mobile originated messages.
You can use a webhook to respond to mobile-originated messages when either the keyword or the information you want to respond with are variable and defined outside of Airship. For example, if users text the defined keyword balance to your sender ID, you can use a webhook to process incoming messages and respond with each individual user’s balance. If a user texts a variable keyword, like order <#orderNumber>, you can use a webhook to respond with the status of the specified order number.
Talk to your Airship account manager to determine the static or variable keywords that you want to route to your webhook.
sequenceDiagram
Audience->>Airship: Sends MO with Keyword
rect rgba(0, 179, 6, .2)
Airship->>Webhook: Forwards MO to Webhook
Webhook-->>Airship: Respond HTTP 200, process asynchronously
note over Airship, Webhook: Airship retries on 429/503 up to 4x
end
Webhook->>Airship: Issue custom response < 10 min
Airship->>Audience: Sends custom response
Airship sends a payload to your webhook server at an /inbound-sms endpoint containing a mobile_originated_id that represents an individual MO message. You will use this ID and send a response using the /sms/custom-response API. Because you are responding to a message sent to you by a member of your audience, custom responses do not require users to opt in. However, the mobile_originated_id has a 10-minute lifespan; you have 10 minutes from the time a mobile-originated message is received to issue a response, after which the mobile_originated_id expires and you will be unable to respond to the inbound message.
Your webhook server must:
Have a public URL. Airship server IPs regularly change and must be able to reach your webhook.
Support an /inbound-sms (POST) endpoint to receive SMS inbound message payloads from Airship. Your webhook should immediately respond with HTTP 200 OK and process responses asynchronously. Long-lived connections can cause performance problems on both systems.
Support a /validate (GET) endpoint. You must respond to a validation request with the Validation Code issued when you set up your webhook in Airship.
Issue responses (to Airship’s /sms/custom-response endpoint) within 10 minutes of the received_timestamp in the /inbound-sms payload.
Accept HTTPS connections.
Airship uses TLSv1.2 with the following accepted cipher suites:
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
Additional Recommendations
Your webhook server should accept up to 100 concurrent connections. Airship will establish concurrent connections with your webhook when concurrent incoming messages require processing.