After your project has been provisioned for SMS notifications and you have successfully registered MSISDNs for your users, you can send SMS messages using the API.
This page explains how to send messages using the API. If you want to send an SMS message through the Airship dashboard, see the SMS Notification Tutorial.
Push API
Send SMS notifications to SMS channels alone, or combine them with other
message types
and platforms, e.g., iOS and Web, using our
Push API.
Example Request: Send to multiple registered channels using a Named User
POST /api/push HTTP/1.1
Authorization:Basic <master authorization string>
Accept:application/vnd.urbanairship+json; version=3;
Content-Type:application/json
{
"audience": {
"named_user": "omnichannel_man"
},
"notification": {
"alert": "Default message, will only go to web channels in this example.",
"android": {
"alert": "Message for Android devices."
},
"sms": {
"alert": "Alert text for SMS."
},
"email": {
"subject": "Omnichannel Test",
"html_body": "<h1>Greetings!</h1><p>Email paragraph text.</p>",
"plaintext_body": "Email paragraph text, plaintext version.",
"message_type": "transactional",
"sender_name": "Airship",
"sender_address": "no-reply@airship.com",
"reply_to": "no-reply@airship.com"
}
},
"device_types": [
"android",
"sms",
"web",
"email"
]
}
Schedule an SMS Message
If you don’t set an SMS channel’s timezone when you register a channel, Airship will attempt to infer the channel’s time zone from its msisdn. You can use time zones to schedule messages at a particular time relative to your audience’s different time zones.
Example Request: Send an SMS in your Audience’s local time
POST /api/schedules HTTP/1.1
Authorization:Basic <master authorization string>
Accept:application/vnd.urbanairship+json; version=3;
Content-Type:application/json
{
"schedule": {
"local_scheduled_time": "2020-03-20T09:15:00"
},
"name": "SMS At Local Time",
"push": {
"audience": {
"tag": "likes_baseball"
},
"device_types": "sms",
"notification": {
"alert": "Are you ready for baseball season? Get geared up for opening day at https://www.sportstuff.com/baseball/opening_day_deals/",
"sms": {
"alert": "Are you ready for baseball season? Get geared up for opening day at https://www.sportstuff.com/baseball/opening_day_deals/",
"shorten_links": true
}
}
}
}
Links in SMS Messages
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.
Tag Actions with Shortened Links
You can add or remove tags from users who engage with shortened links in your SMS messages by adding query parameters to your URLs. Shortened links with tag actions are the same length as URLs without, making it easy to track engagement with your users. You can also use tag change events to kick off automation rules or journeys, making it easier to integrate SMS messaging campaigns into your larger messaging strategy.
Add a tag: ?ua-tag-add=my_tag_group:tag_to_add
Remove a tag: ?ua-tag-remove=my_tag_group:tag_to_remove
You can perform up to 100 total tag actions (add and remove) per SMS message.
The following payload is a simple example in which Airship would apply the blazers tag and remove the no_preference tag in the fav_team tag group for anybody who engages with the link.
