Platform overrides

Override push settings and provide content for specific platforms (selected by device_type). The following schemas represent overrides for each platform.

Android overrides

The platform override section for Android. Maximum 4,096 bytes.

Jump to examples ↓

OBJECT PROPERTIES

actions object<Actions>
Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.
alert string
A string that override the alert value provided at the top level, if any.
category string
Helps determine notification sort order. Available on Android Lollipop+.
Possible values: alarm, call, email, err, event, msg, promo, recommendation, service, social, status, sys, transport
collapse_key string
A key indicating that this message can replace, or be replaced by, another message with the same collapse_key. This feature comes into play when a device is offline (e.g., airplane mode) or in doze mode; if multiple messages are available with the same collapse_key when a device comes back online, it will display only the most recent message and discard previous messages using the same collapse_key.
delay_while_idle booleanDEPRECATED
After November 15, 2016, this was still accepted by GCM, but ignored. When set to true, it indicates that the message should not be sent until the device becomes active. The default value is false.
deliver_to string
Filters out Android channels that are not able to receive notifications. If the value is opted_in, the payload is only sent to opted-in devices. If the value is all, the payload is sent to opted-in and background enabled devices. Defaults to all if not provided.
Possible values: all, opted_in
delivery_priority string
Sets the FCM/GCM priority of the message. Defaults to normal if not provided.
Possible values: high, normal
extra object
A JSON dictionary of string-to-string key-value pairs. The keys from, message_type, data and keys that start with google or gcm are disallowed.
icon string
A string representing an image file included in the application’s resources.
icon_color string
A string representing the icon color in API Color Format. i.e., #rrggbb
interactive object<Interactive notification object>
An interactive notification.
Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.
live_update object
JSON object that represents the content sent to a Live Update notification. Live Updates are an AXP feature.
Note: Using this object transforms the Android notification to a Live Update notification. When event is equal to start, the entire targeted audience will receive the Live Update content. When event is equal to update or end, only devices that have a Live Update started for the specified name field will receive the Live Update content.
OBJECT PROPERTIES
- content_state object
  A dictionary of string keys to arbitrary JSON values that represents the content state to be updated by the Live Activity or Live Update notification.
- dismissal_date integer
  An optional epoch timestamp in seconds, used when you end the Live Update.
- event string
  Use start to start a Live Update. Use update to update a current Live Update. Use end to emit the last update and end the Live Update.
  Possible values: start, update, end
- name string
  The name of the Live Update to target. When event is equal to update or end, the audience will be limited to devices that have a Live Update started for the specified name.
- timestamp integer
  An optional epoch timestamp in seconds, used to enforce the Live Update ordering. If you don’t provide one, the current timestamp is used.
- type string
  Used to map Live Update events to the corresponding handler in your app.
local_only boolean
If true, the notification is only shown on wearable devices.
notification_channel string
A string representing a notification channel. Used to group notifications with similar behavior.
notification_tag string
A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification. Similar to the iOS collapse_id.
priority integer
An integer in the range from -2 to 2 inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority.
public_notification object
An optional notification to show on lock screen instead of the redacted one. This is only useful with visibility set to -1 (private). The object may contain any of the following string fields title, alert, and summary.
OBJECT PROPERTIES
- alert string
- summary string
- title string
sound string
A string representing a sound file name included in the application’s resources.
style object
Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.
OBJECT PROPERTIES
- big_picture string
  If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.
- big_text string
  If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.
- lines array[string]
  An array of strings if the type field is set to inbox.
- summary string
  A string field which will override the summary of the notification.
- title string
  A string field which will override the title of the notification.
- type stringREQUIRED
  Possible values: big_picture, big_text, inbox
summary string
A string representing a summary/subtitle of the notification.
time_to_live object
Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.
One of
- string
  A date-time.
title string
A string representing the title of the notification. The default value is the name of the app.
visibility integer
An integer in the range from -1 to 1 inclusive. 1 = public (default), 0 = private, -1 = secret. Secret does not show any notifications. Private shows a redacted version of the notification.
Possible values: -1, 0, 1
wearable object
Provides options for messages displayed on wearable Android devices.
OBJECT PROPERTIES
- background_image string
  The URL to a background image to display on the wearable device.
- extra_pages array[object]
  An array of objects, each with a title and alert string attributes specifying extra pages of text to appear as pages after the notification alert on the wearable device.
- interactive object<Interactive notification object>
  An interactive notification.
  Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

Used in:

Examples

{
   "android": {
      "title": "Shoe sale",
      "alert": "All the shoes are on sale!",
      "summary": "Don't miss out!",
      "extra": {
          "url": "http://example.com",
          "story_id": "1234",
          "moar": "{\"key\": \"value\"}"
      },
      "icon": "shoes",
      "icon_color": "#8B4513",
      "notification_channel": "promos"
   }
 }

{
   "android": {
      "local_only": true,
      "wearable": {
         "background_image": "http://example.com/background.png",
         "extra_pages": [
            {
               "title": "Page 1 title - optional title",
               "alert": "Page 1 title - optional alert"
            },
            {
               "title": "Page 2 title - optional title",
               "alert": "Page 2 title - optional alert"
            }
         ],
         "interactive": {
            "type": "ua_yes_no_foreground",
            "button_actions": {
               "yes": {
                  "add_tag": "butter",
                  "remove_tag": "cake",
                  "open": {
                     "type": "url",
                     "content": "http://www.urbanairship.com"
                  }
               },
               "no": {
                  "add_tag": "nope"
               }
            }
         }
      }
   }
}

{
   "android": {
       "notification_tag": "push-xyz"
   }
 }

Email overrides

Notification fields specific to email messages. This object is required when email is specified in the payload’s device_types field.

Jump to examples ↓

OBJECT PROPERTIES

attachments array[object]
Optional list of objects, each containing an id string which represents an email attachment.
See Email Attachments
bcc array[string]
An array of email addresses that you want to blind copy on this email. Contact your Account Manager to enable BCC addresses. Using addresses that your Airship Account Manager has not enabled for BCC will return a 400.
bypass_opt_in_level boolean
You can set this toggle when message_type is set to transactional to send a business-critical email. If true, the message will be sent to your entire audience, ignoring transactional_opted_out status.
click_tracking boolean
True by default. Set to false to prevent click tracking for GDPR compliance.
html_body string
The rich-text HTML body of the email, no larger than 100 KB.
- When "message_type": "commercial", the body must contain an unsubscribe link in the format <a data-ua-unsubscribe=“1” title=“unsubscribe”>Unsubscribe</a>. You can send the user to a custom “goodbye” page by providing an href attribute in the link: <a data-ua-unsubscribe=“1” title=“unsubscribe” href=“YOUR_URL”>Unsubscribe</a>. If your unsubscribe link includes an href, Airship unsubscribes the user before redirecting to your page. Additionally, <a data-ua-opt-in=“1” title=“subscribe”>Subscribe and <a data-ua-opt-in=“1” title subscribe" href=“YOUR_URL_HERE”>Subscribe will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.
- See: Email image recommendations.
message_type stringREQUIRED
Must be transactional or commercial. If a message type is specified in the push payload, the email message type must match. Otherwise, it will result in a 400-level error.
Possible values: transactional, commercial
open_tracking boolean
True by default. Set to false to prevent open tracking for GDPR compliance.
plaintext_body stringREQUIRED
The plain text body of the email, no larger than 100 KB.
When "message_type": "commercial", the body must contain a [[ua_unsubscribe]] link, which will be replaced by the unsubscribe link in Airship. You can send the user to a custom “goodbye” page by providing an href in the format [[ua-unsubscribe href=“your url here”]]. If you include an href, Airship unsubscribes the user before redirecting to your page. Additionally, [[ua-opt-in]] and [[ua-opt-in href=“YOUR_URL_HERE”]] will be replaced by a link that will opt the user in to both commercial and transactional messaging and optionally redirect the user to a customer-supplied landing page.
reply_to stringREQUIRED
The reply-to address. The username portion of the reply-to address can be set dynamically using Handlebars. The domain portion of the reply-to address can be any correctly formatted domain.
sender_address stringREQUIRED
The email address of the sender. The domain of the email must be enabled in the email provider at the delivery tier (ie: SparkPost). The username portion of the sender address can be set dynamically using Handlebars. The domain portion of the sender address must match one of your project’s configured email sending domains.
sender_name stringREQUIRED
The common name for the sender, visible to email recipients. The sender name can be set dynamically using Handlebars.
subject stringREQUIRED
The subject line of the email.
url_parameters object
A JSON dictionary of string-to-string key-value pairs as UTM or custom parameters. Each key and value will become a query parameter key and URL-encoded value that are automatically appended to all link URLs in an email. These parameters are used for tracking campaign performance.
If a query parameter defined in this object already exists in a link, it will not be overwritten in the link. Dynamic values are supported using Handlebars, with limitations. See URL parameters in the Email content guide for more information.

Used in:

Examples

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
         "alert": "Hello Android user!"
      },
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "transactional",
         "sender_name": "Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com",
         "click_tracking": false,
         "open_tracking": false,
         "attachments": [
            {
               "id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0",
            },
            {
               "id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"
            }
         ],
         "url_parameters": {
           "utm_source": "airship",
           "utm_channel": "email"
         }
      }
   }
}

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email"
   ],
   "notification": {
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
         "plaintext_body": "Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
         "message_type": "transactional",
         "sender_name": "{{email_sender_name}}",
         "sender_address": "{{email_sender_username}}@airship.com",
         "reply_to": "{{email_reply_to_username}}@airship.com",
      }
   }
}

Fire OS overrides

The platform override section for Kindle Fire (for Amazon Device Messaging).

OBJECT PROPERTIES

actions object<Actions>
Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.
alert string
A string that override the alert value provided at the top level, if any.
consolidation_key string
A string representing a key to suppress previous messages sent with the same key.
expires_after object
Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.
One of
- string
  A date-time.
extra object
A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.
icon string
A string representing an image file included in the application’s resources.
icon_color string
A string representing the icon color in API Color Format. i.e., #rrggbb
interactive object<Interactive notification object>
An interactive notification.
Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.
notification_channel string
A string representing a notification channel. Used to group notifications with similar behavior.
notification_tag string
A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification.
sound string
A string representing a sound file name included in the application’s resources.
style object
Advanced styles big text, big picture, and inbox are available on Android 4.3+ by adding the style to the platform specific notification payload on Android platforms. This object must contain a string field type which must be one of big_picture, big_text, or inbox. It may also contain title and summary override fields.
OBJECT PROPERTIES
- big_picture string
  If the type is set to big_picture, then there must also be a big_picture string field which contains the URL for an image.
- big_text string
  If the type is set to big_text, then a big_text string field must be present with the text to be shown in big text style.
- lines array[string]
  An array of strings if the type field is set to inbox.
- summary string
  A string field which will override the summary of the notification.
- title string
  A string field which will override the title of the notification.
- type stringREQUIRED
  Possible values: big_picture, big_text, inbox
summary string
A string representing a summary/subtitle of the notification.
title string
A string representing the title of the notification. The default value is the name of the app.

Used in:

iOS overrides

The platform override section for iOS. Maximum 4,096 bytes.

Jump to examples ↓

OBJECT PROPERTIES

actions object<Actions>
Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.
alert object
Override the alert value provided at the top level, if any. May be a JSON string or an object which conforms to Apple’s push service spec.
One of
- string
  Alert override text for iOS devices.
- JSON object that conforms to Apple’s Payload Key Reference .
  When using thread_id to group notifications, you might want to use the summary-arg and summary-arg-count keys to help users identify the group.
  OBJECT PROPERTIES
  - action-loc-key string
    If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”.
  - body string
    The content of the alert message.
  - launch-image string
    The name of the launch image file you want to display with the alert. If the user chooses to launch your app, the contents of the specified image or storyboard file are displayed instead of your app’s normal launch image.
  - loc-args array[string]
    An array of strings containing replacement values for variables in your message text. Each %@ character in the string specified by loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.
  - loc-key string
    The key for a localized message string. Use this key, instead of the body key, to retrieve the message text from your app’s Localizable.strings file. The value must contain the name of a key in your strings file.
  - subtitle string
    Additional information explaining the purpose of the notification.
  - subtitle-loc-args array[string]
    An array of strings containing replacement values for variables in your subtitle string. Each %@ character in the string specified by subtitle-loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.
  - subtitle-loc-key string
    The key for a localized subtitle string. Use this key, instead of the subtitle key, to retrieve the subtitle from your app’s Localizable.strings file. The value must contain the name of a key in your strings file.
  - summary-arg string
    A string added to the summary of grouped notifications represented by the thread_id
  - summary-arg-count integer
    The number of summary-arg strings that a group of notifications represented by a thread_id will display.
  - title string
    The title of the notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.
  - title-loc-args array[string]
    An array of strings containing replacement values for variables in your title string. Each %@ character in the string specified by the title-loc-key is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.
  - title-loc-key string
    The key for a localized title string. Specify this key instead of the title key to retrieve the title from your app’s Localizable.strings files. The value must contain the name of a key in your strings file.
badge integer
May be an integer, the value auto, or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either + (U+002B) or - (U+002D). The numeric portion may be an integer value.
category string
Sets the APNs category for the push. This maps directly to the category field in the aps section of the APNs payload. Any interactive notification specified for the IOS platform will take precedence and this value will be ignored (the interactive notification type will be used for the category).
collapse_id string
When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same collapse_id. Similar to the Android notification_tag. The value of this key must not exceed 64 bytes. iOS 10 or above.
content_available boolean
If true, the payload is delivered to your app in the background.
This flag is automatically set to true if there is an In-App Message in the payload. Attempting to override this value to false when there is an in-app message will result in a 400 Bad Request response from the API.
expiry object
Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.
One of
- string
  A date-time.
extra object
A dictionary of string keys to arbitrary JSON values. The key aps would conflict with the generated APNs payload and is disallowed.
filter_criteria string
The criteria the system evaluates to determine if it displays the notification in the current Focus.
interactive object<Interactive notification object>
An interactive notification.
Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.
interruption_level string
Indicates the importance and delivery timing of a notification.
Note: Using a critical interruption level requires a special entitlement from Apple. If you have this entitlement, please contact your Airship Account Manager or our Support team to enable usage for your project.
Possible values: passive, active, time-sensitive, critical
live_activity object
JSON object that represents the content sent to a Live Activity Notification . Live Activities are an AXP feature.
Note: Using this object transforms the iOS notification to a Live Activity notification. Only devices targeted by the Live Activity name field will receive the Live Activity update. Fields outside of the live_activity object will be ignored.
OBJECT PROPERTIES
- alert object
  An optional alert content for the Live Activity push payload.
  On Apple Watch, the system uses the title and body attributes for the alert. On iPhone, the system doesn’t show a regular alert but instead shows the expanded Live Activity in the Dynamic Island. On devices that don’t support the Dynamic Island, the system displays a banner on the Home Screen that uses the expanded view of your Live Activity.
  OBJECT PROPERTIES
  - body string
    The content of the Apple Watch alert message.
  - sound string
    The name of the sound file in your app’s bundle that you want to play for the alert.
  - title string
    The title of the Apple Watch notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.
- attributes object
  The attributes that describe the Live Activity for a start event.
- attributes_type string
  The type of attributes that describe the Live Activity for a start event.
- content_state object
  A dictionary of string keys to arbitrary JSON values that represents the content state to be updated by the Live Activity or Live Update notification.
- dismissal_date integer
  An optional epoch timestamp in seconds, used when you end the Live Activity. If you don’t provide one, the default behavior (after 4 hours) is used.
- event string
  Use start to start a Live Activity. Use update to update a current Live Activity. Use end to emit the last update and end the Live Activity.
  Possible values: start, update, end
- name string
  The name of the Live Activity to target. The audience will be limited to devices that have a Live Activity registered for the specified name.
- priority integer
  Sets the APNs priority of the Live Activity delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). enum: [5, 10]
- relevance_score number
  An optional number, determines which of the Live Activities appears in the Dynamic Island and the order of your Live Activities on the lock screen.
- stale_date integer
  An optional epoch timestamp in seconds, tells the system when the Live Activity content becomes outdated.
- timestamp integer
  An optional epoch timestamp in seconds, used to enforce the Live Activity updates ordering. If you don’t provide one, the current timestamp is used.
media_attachment object
The media_attachment key on the iOS override is a JSON object that describes a media attachment to be handled by the Airship Media Attachment extension in iOS 10.
OBJECT PROPERTIES
- content object
  A JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields
  OBJECT PROPERTIES
  - body string
  - subtitle string
  - title string
- options object
  A JSON object that describes how to display the resource at the URL specified above, with any of the following fields.
  OBJECT PROPERTIES
  - crop object
    A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1. Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. See: Media guidelines.
    OBJECT PROPERTIES
    - height number
      The height of the final crop.
    - width number
      The width of the final crop.
    - x number
      The X offset where the crop begins.
    - y number
      The Y offset where the crop begins.
  - hidden boolean
    A boolean, when true, the thumbnail will be hidden.
  - time integer
    A decimal, the frame of the animated resource that should be used in the thumbnail . For GIFs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail. For video, the value should be the time (in seconds) into the video from which to grab the thumbnail. This value should not be set for static resources like JPGs. If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.
- url stringREQUIRED
  The URL to be downloaded by the Airship Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. Image (5 MB): JPEG, GIF, PNG. Audio (10 MB): AIFF, WAV, MP3, M4A. Video (50 MB): MPEG, MPEG2, MP4, AVI. Although these are the theoretical file size maximums, for performance the actual resources should be much smaller. See Media Guidelines.
mutable_content boolean
When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above. Defaults to false.
priority integer
Sets the APNs priority of the delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value will be 10 if the notification is user-visible (In-App Message payload does not count towards visibility) which means there is either an alert, badge, or sound. If the notification is not user-visible, the priority will default to 5 and it is not legal to override this value to 10. Attempts to do so will cause the API respond with a 400 Bad Request response. enum: [5, 10]
relevance_score number
A number from 0.0 to 1.0. Used to sort notifications for an app. The notification with highest score is featured in the notification summary.
sound string
The name of the sound file in your app’s bundle that you want to play for the alert. If the notification is critical, the dictionary has a key for "name" (equivalent to the current sound string), "volume" (a number between 0 and 1 indicating the volume), and "critical" (a boolean indicating if the alert should override local device settings and still notify).
subtitle string
A string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10.
target_content_id string
The identifier of the window to bring forward when the notification is opened. Used for multi-window content, such as App Clips.
thread_id string
A unique identifier used to group notifications into separate threads in the Notification Center and on the lock screen. Grouped notifications are available beginning with iOS 12.
title string
A short string describing the purpose of the notification. This is provided as a convenience for setting the title in the alert JSON object. If a title is also defined in the alert JSON object, this value is ignored.

Used in:

Examples

{
    "audience": "all",
    "device_types": [
            "ios"
        ],
    "notification": {
        "ios": {
            "thread_id": "sfGiants_news",
            "alert": {
                "title": "Kevin Gausman Throws a Perfect Game",
                "body": "Kevin Gausman stymies the Houston Astros for San Francisco's second perfect game in franchise history.",
                "summary-arg": "San Francisco Giants",
                "summary-arg-count": 1
            },
            "relevance-score": 1.0,
            "interruption_level": "passive",
            "sound": "strike-call",
            "media_attachment": {
                "content": {
                    "title": "Kevin Gausman",
                    "body": "Gausman strikes out Justin Turner"
                },
                "options": {
                    "crop": {
                        "height": 0.5,
                        "width": 0.5,
                        "x": 0.25,
                        "y": 0.25
                    },
                    "time": 15
                },
                "url": "https://media.example.com/media/6nJmrhlu4aL1m/giphy.gif"
            },
            "mutable_content": 1
        }
    }
}

{
   "ios": {
       "collapse_id": "push-xyz"
   }
 }

MMS platform overrides

Provides the content for a push to MMS channels. If sms is in the device_type array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.

Jump to examples ↓

OBJECT PROPERTIES

fallback_text stringREQUIRED
If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content.
shorten_links boolean
If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.
When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with &:
- ?ua-tag-add=tag_group:tag&another_group:tag2 — adds a tag in tag_group to the channel_id.
- ?ua-tag-remove=tag_group:tag&another_group:tag2 — removes a tag in tag group from the channel_id.
- ?ua-list-add=subscription_list_id — adds the user’s channel to the subscription list.
- ?ua-list-remove=subscription_list_id — removes the user’s channel from the subscription list.
slides array[object]REQUIRED
An array containing a single slide object. A slide is a multimedia object.
subject string
The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid.

Used in:

Examples

{
   "mms": {
      "subject" : "Double Rainbows",
      "fallback_text": "See https://urbanairship.com/double-rainbows?ua-tag-add=rainbows:used_fallback_text for double rainbows!",
      "shorten_links": true,
      "slides" : [
         {
            "text": "A double rainbow is a wonderful sight where you get two spectacular natural displays for the price of one.",
            "media": {
               "url": "https://www.metoffice.gov.uk/binaries/content/gallery/mohippo/images/learning/learn-about-the-weather/rainbows/full_featured_double_rainbow_at_savonlinna_1000px.jpg",
               "content_type": "image/jpeg",
               "content_length": 238686
            }
         }
      ]
   },
   "device_types": ["sms"]
}

Open channel override

The platform override section for open platforms uses the prefix attribute open:: before the configured open platform name. The open::<open_platform_name> object will contain an object with the following attributes.

Jump to examples ↓

OBJECT PROPERTIES

alert string
Override the alert value provided at the top level, if any.
extra object
A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.
interactive object<Interactive notification object>
An interactive notification.
Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.
media_attachment string
A URI for an image or video somewhere on the internet.
summary string
A string value for providing a content summary.
title string
A string representing the title of the notification.

Used in:

Examples

{
   "audience" : {
      "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "open_channel" : "6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab" } ]
   },
   "notification" : {
      "alert" : "Someone did sports!",
      "ios" : {
         "extra" : {
            "url" : "http://www.example.com" } },
      "open::sms" : {
         "alert" : "SMS override alert value! I will replace the top-level alert.",
         "extra" : {
            "sms_key" : "Some SMS specific payload data for all SMS devices." } },
      "open::email" : {
         "alert" : "Email override alert value! I will replace the top-level alert.",
         "title" : "A title for email payloads - neat!" }
   },
   "options" : { "expiry" : 60 },
   "device_types" : [ "ios", "open::sms", "open::email" ]
}

{
   "alert": "A generic alert sent to all open platforms",
   "device_types" : ["open::sms", "open::email"],
   "open::sms": {
      "title": "SMS Alert!",
      "alert": "A shorter alert for SMS users",
      "summary": "A longer summary of some content or whatever",
      "media_attachment": "https://example.com/cat_standing_up.jpeg",
      "extra": {
         "some_info": "For SMS only",
         "some_id": "671ecd12-ad56-4b2f-98f1-107ce33d33e6" },
      "interactive": {
         "type": "ua_yes_no_foreground",
         "button_actions": {
            "yes": {
               "open": {
                  "type": "url",
                  "content": "http://www.example.com" } },
            "no": {
               "app_defined": {
                  "foo": "bar" } } } }
   },
   "open::email": {
      "alert": "A longer alert for users of email, who have more space." }
}

SMS platform overrides

Provides override options when sms is one of the device_types specified in the payload.

Jump to examples ↓

OBJECT PROPERTIES

alert string
Overrides the alert provided at the top level of the notification for SMS channels. The maximum length of an SMS alert is 1,600 characters. The alert will be split into multiple messages by CLX if needed.
expiry object
The time after which Airship will stop trying to deliver an SMS message. The maximum expiry period is 48 hours; this is also the default expiry period.
One of
- string
  A date-time. The timestamp must be within the next 48 hours.
shorten_links boolean
If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.
When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with &:
- ?ua-tag-add=tag_group:tag&another_group:tag2 — adds a tag in tag_group to the channel_id.
- ?ua-tag-remove=tag_group:tag&another_group:tag2 — removes a tag in tag group from the channel_id.
- ?ua-list-add=subscription_list_id — adds the user’s channel to the subscription list.
- ?ua-list-remove=subscription_list_id — removes the user’s channel from the subscription list.

Used in:

Examples

{
    "audience": {
       "named_user": "user"
    },
    "notification": {
       "alert": "A generic alert sent to all platforms without overrides in device_types",
       "sms": {
          "alert": "A shorter alert with a link for SMS users to click https://www.example.com/long/form/url?ua-tag-add=this_group:this_tag",
          "expiry": 172800,
          "shorten_links": true
       }
    },
    "device_types": [ "sms" ]
}

Web overrides

The web platform overrides determine message behaviors for web notifications.

Safari behaves differently from other browsers and supports only the alert and title overrides. It ignores all other web overrides.

Jump to examples ↓

OBJECT PROPERTIES

actions object<Actions>
Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.
alert string
Override the alert value provided at the top level, if any.
buttons array[object]
Contains one or two buttons that perform actions for the web notification. If you do not specify actions for a button, the button closes the notification without performing an action.
extra object
A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.
icon object
A JSON object that describes an icon to be used with the notification.
OBJECT PROPERTIES
- url stringREQUIRED
  The URL to be used for the icon.
image object
A JSON object that describes an image to be used with the web alert.
OBJECT PROPERTIES
- url stringREQUIRED
  The URL to be used for the image.
require_interaction boolean
If true, a feature that requires a user to interact with the notification in order to remove it from their computer screen.
time_to_live object
Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.
One of
- string
  A date-time.
title string
A string representing the title of the notification.

Used in:

Examples

{
   "audience": {
      "channel": "cab69081-0196-4f6b-91dc-53bc88a2e6ce"
   },
   "device_types": [
      "web"
   ],
   "notification": {
      "alert": "Hello, world!",
      "web": {
         "alert": "Hello Web World",
         "title": "A Custom Web Title",
         "require_interaction": true,
         "buttons": [
            {
               "id": "yes",
               "label": "Yes",
               "actions": {
                  "open": {
                     "type": "home"
                  },
                  "add_tag": [
                     "new_tag"
                  ]
               }
            },
            {
               "id": "no",
               "label": "No"
            }
         ],
         "extra": {
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
         }
      }
   }
}