Message Reference

Feature and usage reference for Urban Airship Messages. See also: Message and Workflow Types.

Channel Registration Requirements

This table represents the minimum requirements for communicating with the various channels supported by Urban Airship. A channel must either have installed the SDK or be registered via the API.

Channel TypeAPI RegistrationSDK Registration
Mobile App✓
Web Browser✓
Email✓
SMS✓
Open Channel✓✓

API Equivalents

Additional API equivalents are noted in the various tables in this document.

Messages

Message TypeAPI Object
Push Notification"notification": {}
Web Push Notification"notification": { "web": {}}
In-App Message"in_app": {} 1
Message Center"message": {}
Apple News NotificationNot supported
Email Notification"notification": { "email": {}}
SMS Notification"notification": { "sms": {}}

1 There is currently no server API for In-App Automation.

Workflows

A workflow is a method of creating messages via the dashboard. See Message and Workflow Types for definitions of each and to learn which message types can be used with each workflow and API endpoint.

Workflow TypeAPI Endpoint
Message/push
A/B Test/experiments
Automation/pipelines
In-App AutomationNot supported
Apple NewsNot supported

Optional Features

See Platform Overrides for API documentation.

Optional Message FeaturesAPI Object
Buttonsinteractive
Titletitle
Summarysummary
Media (iOS)media_attachment
Media (Android and Amazon)style
Badge1badge
Sound1sound
Notification category2notification_channel
Icon3icon

1 iOS only.
2 Android only.
3 Web only.

Availability: Channels Per Workflow Type

Workflow TypeChannels
Message

and

Automation

  • App
  • Web
  • SMS
  • Email
  • Open Channels
A/B Test
  • App
  • Web
In-App Automation
  • App
Apple News
  • Apple News app

Display Format and Timing

Delivery applies to message types and their equivalent API objects.

Message TypeDisplay FormatDisplay Timing
Push NotificationBannerUpon receipt.
Silent Push NotificationNoneNot displayed.
Web Push NotificationBannerUpon receipt, as long as the browser is open.
In-App MessageBanner, modal, or fullscreenUpon opening the app.
Message CenterFullscreenAvailable in the app's Message Center.
Apple News NotificationBannerUpon receipt. If the selected story is still processing, it will send when the story is live.
Email NotificationTemplate layout, HTML, or plain-textUpon opening the message.
SMS NotificationTextUpon receipt.

Message Types and Allowed Combinations

Available message types and combinations per workflow and template types.

Messages Per Workflow Type

Available message types and combinations per workflow type and their equivalent API endpoints.

  • Silent Push Notifications and Apple News Notifications cannot be combined with any other message types.
  • Upload Users (Create and Send in the API) can only be used with a single channel at a time.
Important

The message types you can combine are determined by the channels you select.

In particular, when you select both app (iOS, Android, Amazon) and non-app (Web, Email, SMS, Open Channel) platforms, you cannot include Message Center.

Workflow TypeMessage TypeAllowed Combinations
Message

and

Automation

  • Push Notification
  • Silent Push Notification
  • Web Push Notification
  • In-App Message
  • Message Center
  • SMS Notification
  • Email Notification
  • Push Notification + Web Push Notification + In-App Message

  • Push Notification + Web Push Notification + In-App Message + SMS Notification + Email Notification
Any combination of:

  • Push Notification
  • In-App Message
  • Message Center

Any combination of:

  • Push Notification
  • In-App Message
  • Email Notification
  • SMS Notification

    • Any combination of:

  • Push Notification
  • Web Push Notification
  • Email Notification
  • SMS Notification
    • A/B Test
    • Push Notification
    • Web Push Notification
    • In-App Message
    • Push Notification + Web Push Notification

    • Push Notification + In-App Message

    • Push Notification + Web Push Notification + In-App Message
    In-App Automation
    • In-App Message
    		Not supported
    Apple News
    • Apple News Notification
    		Not supported

    Messages Per Template Type

    Available message types and combinations per template type.

    Template TypeMessage TypesAllowed Combinations
    Push1
    • Push Notification
    • Silent Push Notification
    • In-App Message
    • Push Notification + In-App Message
    Email
    • Email Notification
    		Not supported

    1 Available message types are reduced to those supported by all the channels enabled for your project.

    Workflows and Templates Per Message Type

    Available workflows and templates per message type and their equivalent API objects.

    Message TypeWorkflow TypesTemplate
    Push Notification
    • Message
    • A/B Test
    • Automation
    Silent Push Notification
    • Message
    • Automation
    Web Push Notification
    • Message
    • A/B Test
    • Automation
    In-App Message
    • Message
    • A/B Test
    • Automation
    • In-App Automation
    Message Center
    • Message
    • Automation
    Apple News Notification
    • Apple News
    Email Notification
    • Message
    • Automation
    SMS Notification
    • Message
    • Automation

    Actions

    Message actions apply to the Message, A/B Test, and Automation workflows and their equivalent API endpoints, as well as Push Templates. They are related to these message types only:

    • Push Notification
    • Web Push Notification
    • In-App Message
    • Message Center

    Push notifications and web push notifications use the same configuration screen. See Web Notify to understand differences in behavior.

    Note

    The In-App Automation workflow has the same button actions available in every message.

    Workflows

    Available message actions depending on selected message types. Combining all three message types gives you the same available actions as Push Notification + In-App Message.

    Message ActionAPI ObjectPush Notification

    (with or without Message Center)

    		In-App Message

    (with or without Message Center)

    		Push Notification + In-App MessageMessage Center
    Home✓✓
    Message Center✓1✓1✓✓2
    Landing Page1open3✓✓✓
    Deep Linkopen4✓✓✓
    Adaptive Linkopen5✓✓✓
    Web Pageopen5✓✓✓
    Shareshare✓✓✓

    1 When Message Center is combined with another message type, the Actions dropdown menu defaults to Message Center, but you may choose another action.
    2 When Message Center is the only selected message type, the Actions dropdown menu is replaced by a Rich Page create button.
    3 With type attribute landing_page.
    4 With type attribute deep_link.
    5 With type attribute url.

    Web Notify

    When Web Browsers is the only selected audience channel, the only available actions will be Home, Adaptive Link, and Web Page.

    When combining a Web Push Notification with mobile app Push Notifications and In-App Messages, you may select from these Message Actions:

    • Home: Opens the app's home screen for mobile users. Home for web browsers is the default URL configured in the Web Notify setup.
    • Adaptive Link
    • Web Page
    • Landing Page
    • Deep Link

    Landing Page and Deep Link are for mobile app users only. When Web Browsers is an included channel and Deep Link or Landing Page is chosen as the message action, also enter a Web Page URL for your Web Notify audience.

    Rich Pages

    Rich Pages can be configured with buttons that perform these actions:

    • Deep Link
    • URL
    • Share

    See: Message Actions: Rich Pages.

    Templates

    Push templates support these actions:

    • Home
    • Deep Link
    • Adaptive Link
    • Web Page

    The same actions are available for push notifications, in-app messages, or combining the two.

    Configuration and Requirements

    Actions that do not require configuration cannot be disabled from appearing in the dashboard, and do not have a minimum SDK:

    • Home

    Actions that require configuration, can be disabled from appearing in the dashboard, and have a minimum SDK:

    • Message Center
    • Landing Page
    • Deep Link
    • Adaptive Link
    • Web Page (URL)

    The minimum SDK version is listed in Settings » Configuration » Composer, along with an enable/disable toggle. The Adaptive Link action is enabled via the UA Actions Framework.

    The Share action is an exception. It requires configuration, cannot be disabled from appearing in the dashboard, and its minimum SDK is 4.0.

    Delivery

    Delivery applies to workflows and their equivalent API endpoints.

    • The In-App Automation workflow does not have delivery settings. The messages are instead stored on the user’s device then displayed according to the triggers you define.

    Equivalent API endpoints are noted.

    Workflow TypeImmediateScheduled1Optimal Time2During Available Window
    Message/push/schedules✓3
    A/B Test/experiments/experiments
    Automation/pipelines/pipelines4✓
    In-App Automation
    Apple News
    ✓5

    1 Scheduled messages must contain a schedule object.
    2 Optimal Time is one of our Predictive features. Please contact your Urban Airship Account Manager to purchase.
    3 In the API, Optimal Time uses the schedule specification best_time.
    4 See: Automation Timing.
    5 If the selected story is still processing, it will send when the story is live.

    Automation Timing

    Workflow OptionAPI Object
    Delaydelay object with seconds attribute
    Scheduledate object with start and end attributes
    Send during available windowdate object with recent attribute

    Optional Delivery Features

    These apply to the workflow Optional Delivery Features only. Also refer to their entries in the API Platform Overrides documentation. For Start and End Dates, see the API Automation documentation.

    Workflow OptionAPI Object
    Start Dateactivation_time1
    End Datedeactivation_time1
    Expirationexpiry
    Custom Keysextra
    Background Processing1,2content_available
    Mutable Content1mutable_content
    Group2thread_id
    Critical2critical
    Collapse Key (iOS)collapse_id
    Collapse Key (Amazon)consolidation_key
    Collapse Key (Android)collapse_key
    Delay While Idle3delay_while_idle
    Delivery Priority3delivery_priority
    Require Interaction4require_interaction

    1 Used with Automation only.
    2 iOS only.
    3 Android only.
    4 Web only.