1. Home
  2. /Developer
  3. /REST APIs
  4. /Airship API
  5. /Data Formats
  6. /Additional Schemas

Additional Schemas

Schemas that are not grouped by a specific tag. These include core data objects and shared schemas used across multiple operations.

Actions

Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

Jump to examples ↓

OBJECT PROPERTIES
  • add_custom_event object

    Emit a custom event when a user interacts with the push notification.

    OBJECT PROPERTIES
    • name stringREQUIRED

      The name of the custom event.

    • properties object

      A JSON object with the properties associated with the event.

    • value number

      An integer or decimal value of the event.

  • add_tag array[string]

    An array of tags.

  • app_defined object

    A map of registered action names to payloads as defined by the app or SDK. Some of these actions are supported as their own property on the Actions object, but be aware that their registered names in the SDK may be different. For a summary of the actions registered by the SDK, including usage information, see the Mobile docs.

  • open object

    Open action. When a user interacts with the notification, opens one of: URL, deep link, or landing page as described in the associated content property.

    One of
    • Open URL Action object

      Opens a URL or passes a string for use as a custom action.

      OBJECT PROPERTIES
      • content stringREQUIRED

        Any string. A URL string that starts with either http or https will open a URL or a string that starts with tel: followed by a sequence of numbers will open the phone app.

      • type stringREQUIRED

        Possible values: url

    • Open Deep Link Action object

      Opens a deep link.

      OBJECT PROPERTIES
      • content stringREQUIRED

        A non-blank string.

      • fallback_url string

        A URL that can be used on platforms that don’t have full support for the otherwise defined action.

      • type stringREQUIRED

        Possible values: deep_link

    • Open Landing Page object

      Opens a landing page.

      OBJECT PROPERTIES
  • remove_tag array[string]

    An array of tags.

  • share string

    String indicating the text that will populate the share action.

  • subscription_list array[object]

    Alter subscription list membership for a channel or contact.

Used in:

Examples

Example add custom event action

{
   "actions": {
       "add_custom_event": {
          "name": "myCustomEvent",
          "value": 12.5,
          "properties": {
             "property_key1": "value_property1",
             "property_key2": 6789
          }
       }
   }
}

Example tag actions

{
   "actions": {
      "add_tag": [
         "airship",
         "blimp"
      ],
      "remove_tag": [
         "boat",
         "car"
      ],
      "share": "Check out Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": {
         "some_app_defined_action": "some_value"
      }
   }
}

Example landing page action

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8"
         },
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

Example open phone app

{
   "actions": {
      "open": {
         "type": "url",
         "content": "tel:15035551234"
      }
   }
}

Example deep link action

{
   "actions": {
      "open": {
         "type": "deep_link",
         "content": "prefs",
         "fallback_url": "https://www.urbanairship.com/settings"
      }
   }
}

Example Subscription List action

{
   "actions": {
      "subscription_list": [
         {
            "action": "subscribe",
            "type": "contact",
            "list_id": "cool_deals",
            "scope": "app"
         }
      ]
   }
}

Array

The array can hold string, number, boolean, objects, and array. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. Objects must be valid JSON or the request will fail.

Audience limits object

Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See Audience Limit in the Message delivery user guide for additional information and limitations.

Jump to examples ↓

OBJECT PROPERTIES
  • max_recipients integer

    The maximum number of recipients a push can be delivered to.

Used in:

Examples

Audience limits

{
  "options": {
    "audience_limits": {
      "max_recipients": 1000
    }
  }
}

Ban List parameters

A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a Ban List request URL.

Jump to examples ↓

OBJECT PROPERTIES
  • * string

Used in:

Examples

Ban List parameters

{
  "ban_list_parameters": {
    "category": "api-cat"
  }
}

Campaigns object

An object specifying custom campaign categories related to the notification.

Jump to examples ↓

OBJECT PROPERTIES
  • categories array[string]REQUIRED

    Array of strings representing the campaigns you wish to associate with the notification. Must have between 1 to 10 items in the array with a 64 character/byte maximum per item.

Used in:

Examples

Example campaigns in a push payload

{
   "audience": "all",
   "notification": {
      "alert": "Taco Kitten wins Kentucky Derby by a whisker"
   },
   "campaigns": {
      "categories": [
         "kittens",
         "tacos",
         "horse_racing"
      ]
   },
   "device_types": [ "ios", "android" ]
}

Channel Contact operation device info object

Additional device information that is not included in the headers.

OBJECT PROPERTIES
  • device_type stringREQUIRED

    The device type of the channel.

    Possible values: ios, android, amazon, web, email, sms, open

Channel Contact operation object

Contains device_info and action.

OBJECT PROPERTIES
  • action objectREQUIRED
    One of
    • Channel Contact Operation Resolve Action Object

      A Channel Contact operation using this object results in either resolving the current associated Contact (named or anonymous) for that channel or it will associate that channel to an Anonymous Contact, always returning a Contact ID for the SDK to store. A Contact ID can optionally be provided, which the channel will be associated to in the event the channel is not already associated to a Contact and the provided Contact ID is not already bound to a Named User.

    • Channel Contact Operation Identify Action Object

      A Channel Contact operation using this object associates a channel to a Named User and attempts to identify the Named User with a specific Contact ID. If the Named User does not yet exist, it will be created with the Anonymous Contact ID that the channel is already associated to. If the channel is not associated to an Anonymous Contact, the Named User will be created using the optionally provided Contact ID or a randomly generated Contact ID if there is no Contact ID provided or the provided Contact ID is already bound to a Named User.

    • Channel Contact Operation Reset Action Object

      A Channel Contact operation using this object is mostly equivalent to Named Users disassociation, but instead of leaving the channel disassociated, it associates the channel to a new Anonymous Contact after disassociation from the current Contact.

  • device_info object<Channel Contact operation device info object>REQUIRED

    Additional device information that is not included in the headers.

Channel listing object

Describes a channel listing object.

Jump to examples ↓

OBJECT PROPERTIES
  • address string

    The address to send push notifications to when device_type is email or open. For all other device_type values, this key is replaced with push_address.

  • alias stringDEPRECATED

    Displays the alias associated with the channel, if one exists. Aliases are the precursor to Named Users, our user mapping system. If you are using aliases, please upgrade to Named Users. Listed as null when not set.

  • attributes object<Custom and predefined Attributes>

    A dictionary of attributes that you’ve associated with the channel. See the Attributes guide for more information about creating and assigning attributes.

    The attributes listed here are “predefined” by Airship, but you can create new attributes in the Airship dashboard.

    Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

    This object enumerates predefined attributes, but you can create your own in the Airship dashboard.

  • background boolean

    If true, the device can receive background push notifications. If false, it cannot. This field only appears for iOS devices.

  • channel_id string

    The unique channel identifier for a device.

  • commercial_opted_in string

    The date-time when a user gave explicit permission to receive commercial emails.

  • commercial_opted_out string

    The date-time when a user explicitly denied permission to receive commercial emails.

  • created string

    The creation date-time of this channel.

  • device_attributes object<Device Attributes>

    Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: Default Attributes.

    For segmentation, when using ua_app_version, ua_sdk_version, or ua_device_os, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., 12.2.3-alpha is compared as 12.2.3. You can use operators equals, contains, less, greater, is_empty with values in the formats 1, 1.2, 1.2.3.

  • device_type string

    Specifies the device platform for a channel.

    Possible values: ios, android, amazon, web, open, email, sms

  • email_address string

    The email address associated with the email channel when device_type is email.

  • installed boolean

    If true, the channel is installed. If false, it is uninstalled.

  • ios object<iOS channel object>

    Contains parameters that apply when the device_type is set to ios.

  • last_registration string

    The last registration date-time of this channel, if known.

  • msisdn string

    The phone number associated with the SMS channel. Must be numeric characters only, without leading zeros.

  • named_user_id string

    A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Listed as null when not set.

  • open object<Open channel options>

    Contains options that apply when the device_type is set to open.

  • opt_in boolean

    If true, the channel is opted in to push notifications. If false, it is not. Required for all types except email.

  • opt_in_date string

    (SMS only) The date-time when the SMS channel gave permission to receive messages.

  • opt_out_date string

    (SMS only) The date-time when the SMS channel opted out of receiving messages.

  • push_address string

    Required if opt_in is true. The address to send push notifications to for all device_type values other than email and open. When device_type is email or open, this key is replaced with address.

  • subscription_lists array

    Lists all the subscription lists that this channel is subscribed to.

  • suppression_state string

    If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use imported.

    Possible values: spam_complaint, commercial_spam_complaint, bounce, imported

  • tag_groups object<Tag Group object>

    One or more tag group objects (including Device Property Tags) associated with this channel.

    Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

    A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

  • tags array[string]

    An array of tags associated with this channel.

  • transactional_opted_in string

    The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.

  • transactional_opted_out string

    The date-time when a user explicitly denied permission to receive transactional emails.

  • web object

    Contains parameters that apply when the device_type is set to web.

    OBJECT PROPERTIES
    • subscription object

      The web subscription. This optional field is not present for cases where a browser is registered (for purposes of Feature Flags) but isn’t opted-in to push notifications.

      OBJECT PROPERTIES
      • keys object

        Encryption keys required for signing the push package.

        OBJECT PROPERTIES
        • auth string

          The authentication secret.

        • p256dh string

          The public key.

    • user_agent_string string

      The full user agent string.

Used in:

Examples

Example iOS channel

{
   "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
   "device_type": "ios",
   "installed": true,
   "background": true,
   "opt_in": false,
   "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
   "created": "2020-08-08T20:41:06",
   "last_registration": "2020-05-01T18:00:27",
   "named_user_id": "some_id_that_maps_to_your_systems",
   "alias": null,
   "tags": [
      "tag1",
      "tag2"
   ],

   "tag_groups": {
      "sports fan": ["Federer fan", "Messi fan"],
      "music fan": [ "Beyonce", "Muse" ],
      "ua_locale_country": [ "US" ],
      "ua_locale_language": [ "en" ]
   },

   "ios": {
      "badge": 0,
      "quiettime": {
         "start": null,
         "end": null
      },
      "tz": "America/Los_Angeles"
   }
}

Custom Event object

Defines a Custom Event.

Jump to examples ↓

OBJECT PROPERTIES
  • body objectREQUIRED

    Contains information about your Custom Event. While only the event name is required, it is recommended that you provide as much information in this object as possible, so that your event is relevant and informative.

    OBJECT PROPERTIES
    • interaction_id string

      The identifier defining where the event occurred. In a traditional website, this would be the path and query string from the URL. In a single page app that uses hash routing, it would be the path, query string, and fragment identifier.

    • interaction_type string

      Describes the type of interaction that triggered the event, e.g., url, social, email. This should almost always be ‘url’ for web events. Airship can separate events with the same name by interaction_type, providing greater insight into Custom Events.

    • name stringREQUIRED

      A plain-text name for the event. Airship’s analytics systems will roll up events with the same name, providing counts and total value associated with the event. This value cannot contain upper-case characters. If the name contains upper-case characters, you will receive a 400 response.

    • properties object

      An object containing Custom Event properties. You can use handlebars to access Custom Event properties in templates or messages triggered by the Custom Event. Items in the properties object are limited to a 255 character maximum string length.

    • session_id string

      The user session during which the event occurred. You must supply and maintain session identifiers.

    • transaction string

      If the event is one in a series representing a single transaction, use the transaction field to tie events together.

    • unique_id string

      If properties for the Custom Event are being used for triggering and personalizing a Sequence, use a unique ID to introduce uniqueness in order to differentiate messages and prevent dropping sends as duplicates.

    • value number

      If the event is associated with a count or amount, the ‘value’ field carries that information. Airship will treats this field as a representation of money; mathematical operations will use fixed precision representations of this field. The value field respects six digits of precision to the right of the decimal point. This field is optional; if empty, its value will default to zero.

  • occurred string

    The date-time when the event occurred. Events must have occurred within the past 90 days. You cannot provide a future date-time. If omitted, the current date-time is used.

  • user objectREQUIRED

    Contains the Airship channel identifier for the user who triggered the event.

    One of
    • Named User object
      OBJECT PROPERTIES
      • named_user_id string

        The Named User associated with the event.

    • Fire OS Channel object
      OBJECT PROPERTIES
      • amazon_channel string

        The unique channel identifier for a Fire OS device.

    • Android Channel object
      OBJECT PROPERTIES
      • android_channel string

        The unique channel identifier for an Android device.

    • iOS Channel object
      OBJECT PROPERTIES
      • ios_channel string

        The unique channel identifier for an iOS device.

    • Web Channel object
      OBJECT PROPERTIES
      • web_channel string

        The unique channel identifier for a web device.

    • Generic Channel object
      OBJECT PROPERTIES
      • channel string

        Airship canonical identifier for a user. Airship will determine the device.

Used in:

Examples

Example Custom Event

{
   "occurred": "2020-05-02T02:31:22",
   "user": {
       "named_user_id": "cool.person"
   },
   "body": {
       "name": "purchased",
       "value": 239.85,
       "transaction": "686f53d4-7e0s-36d7-234e-c9792dac6e7b",
       "interaction_id": "your.store/us/en_us/pd/shoe/pid-123456/pgid-123456",
       "interaction_type": "email",
       "unique_id": "4c2c380a-0400-4d34-ab04-aaf31f0967c7",
       "properties": {
          "description": "sky high",
          "brand": "victory",
          "colors": [
          "red",
          "blue"
          ],
          "items": [
          {
             "text": "New Line Sneakers",
             "price": "$ 79.95"
          },
          {
             "text": "Old Line Sneakers",
             "price": "$ 79.95"
          },
          {
             "text": "Blue Line Sneakers",
             "price": "$ 79.95"
          }
          ],
          "name": "Cool Person",
          "userLocation": {
          "state": "CO",
          "zip": "80202"
          }
       },
      "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
   }
}

Email channel associated by contact

An email channel associated with a contact.

Jump to examples ↓

OBJECT PROPERTIES
  • channel_id string

    The unique identifier.

  • commercial_opted_in string

    The date-time when a user gave explicit permission to receive commercial emails.

  • email_address string

    The email address corresponding to the channel.

  • type string

    The channel type.

    Possible values: email

Examples

Example

{
  "type": "email",
  "channel_id": "463c4643-a16c-48da-9585-f2c5406f828b",
  "email_address": "d*******r@example.com",
  "commercial_opted_in": "2024-02-11T00:00:00"
}

Experiment object

An experiment object describes an A/B test, including the audience and variant portions.

Jump to examples ↓

OBJECT PROPERTIES
  • audience object<Audience selector (max 1000)>REQUIRED

    The audience for the experiment.

    An audience selector forms the expression that determines the set of channels to target.

  • campaigns object<Campaigns object>

    Campaigns object that will be applied to resulting pushes.

    An object specifying custom campaign categories related to the notification.

  • control number

    The proportional subset of the audience that will not receive a push. The remaining audience will be split between the variants. It may help to think of this value as a percentage. See Audience groups in the API in Message A/B tests.

  • created_at string

    The date-time when the experiment was created. This value is created and assigned automatically by Airship and appears in responses only.

  • description string

    A description of the experiment.

  • device_types array[string]REQUIRED

    An array containing one or more strings identifying targeted platforms.

  • id string

    The unique ID assigned to this experiment. This value is created and assigned automatically by Airship and appears in responses only.

  • name string

    A name for the experiment.

  • push_id string

    The push ID associated with this experiment. This value is created and assigned automatically by Airship and appears in responses only.

  • variants array[object]REQUIRED

    The variants for the experiment. An experiment must have at least 1 variant and no more than 26.

Used in:

Examples

Example

{
   "name": "<experiment name>",
   "description": "<experiment description>",
   "control": "<control group>",
   "audience": "<audience-selection>",
   "device_types": "<device-types>",
   "campaigns": "<campaigns>",
   "variants": "[<variant specifications>]",
   "id": "<id>",
   "created_at": "timestamp",
   "push_id": "<push_id>"
}

Identify action object

A Channel Contact operation using this object associates a channel to a Named User and attempts to identify the Named User with a specific Contact ID. If the Named User does not yet exist, it will be created with the Anonymous Contact ID that the channel is already associated to. If the channel is not associated to an Anonymous Contact, the Named User will be created using the optionally provided Contact ID or a randomly generated Contact ID if there is no Contact ID provided or the provided Contact ID is already bound to a Named User.

Jump to examples ↓

OBJECT PROPERTIES
  • contact_id string

    Contact ID to associate to the Named User if it is not already associated to a Contact. Otherwise it will be ignored.

  • named_user_id stringREQUIRED

    Identifies the Named User, with no leading or trailing whitespace.

  • type stringREQUIRED

    The action to be carried out.

    Possible values: identify

Examples

Example identify contact operation

{
  "device_info": {
    "device_type": "android"
  },
  "action": {
    "type": "identify",
    "named_user_id": "my-named-user",
    "contact_id": "a29ce8c7-4a63-37cb-9716-dffd3d419c4a"
  }
}

Identify Contact response object

Information about the Contact.

OBJECT PROPERTIES
  • channel_association_timestamp string

    The date-time when the channel association occurred.

  • contact_id string

    Internal Contact ID.

  • is_anonymous boolean

    Specifies whether the Contact is anonymous or not.

In-app message

A JSON object describing an in-app message payload.

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 stringREQUIRED

    The text displayed on the in-app message.

  • display object

    The allowed fields for this object depend on the value of of the display_type field. Currently, the only valid display_type is banner, so the following is an associated display object for the banner display type.

    OBJECT PROPERTIES
    • duration integer

      Specifies how long the notification should stay on the screen in seconds before automatically disappearing; set to 15 by default.

    • position string

      One of either top or bottom, specifies the screen position of the message. Defaults to bottom.

      Possible values: top, bottom

    • primary_color string

      Specifies the primary color of the in-app message (format #rrggbb).

    • secondary_color string

      Specifies the secondary color of the in-app message (format #rrggbb).

  • display_type stringREQUIRED

    Specifies the display type.

    Possible values: banner

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • 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.

Used in:

Examples

Example

{
   "audience": "all",
   "device_types": [ "ios", "android" ],
   "notification": { "alert": "This part appears on the lockscreen" },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      },
      "actions": {
         "add_tag": "in-app"
      }
   }
}

Interactive notification object

An interactive notification.

Attempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.

Jump to examples ↓

OBJECT PROPERTIES
  • button_actions object

    An object containing keys that must be the button IDs for the specified interactive notification type. If the notification type begins with ua_, the keys must match exactly the button IDs for that type or a strict subset. The names of the button IDs cannot be validated for custom notifications.

    One of
    • Yes/No object

      Yes/No button action

      OBJECT PROPERTIES
      • no object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • yes object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Accept/Decline object

      Accept/decline button action

      OBJECT PROPERTIES
      • accept object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • decline object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Shop Now object

      Shop now button action

      OBJECT PROPERTIES
      • shop_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Buy Now object

      Buy now button action

      OBJECT PROPERTIES
      • buy_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow object

      Follow button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In object

      Opt in button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Unfollow object

      Unfollow button action

      OBJECT PROPERTIES
      • unfollow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt Out object

      Opt out button action

      OBJECT PROPERTIES
      • opt_out object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In/Remind object

      Opt in/remind button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Remind object

      Remind button action

      OBJECT PROPERTIES
      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • More Info object

      More info button action

      OBJECT PROPERTIES
      • more_info object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Download object

      Download button action

      OBJECT PROPERTIES
      • download object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Share object

      Share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Download/Share object

      Download/share button action

      OBJECT PROPERTIES
      • download object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Remind/Share object

      Remind/share button action

      OBJECT PROPERTIES
      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt In/Share object

      Opt in/share button action

      OBJECT PROPERTIES
      • opt_in object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Opt Out/Share object

      Opt out/share button action

      OBJECT PROPERTIES
      • opt_out object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow/Share object

      Follow/share button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Unfollow/Share object

      Unfollow/share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • unfollow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Shop Now/Share object

      Shop now/share button action

      OBJECT PROPERTIES
      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • shop_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Buy Now/Share object

      Buy now/share button action

      OBJECT PROPERTIES
      • buy_now object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • More Like/Less Like object

      More like/less like button action

      OBJECT PROPERTIES
      • less_like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • more_like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like/Dislike object

      Like/dislike button action

      OBJECT PROPERTIES
      • dislike object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like object

      Like button action

      OBJECT PROPERTIES
      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Like/Share object

      Like/share button action

      OBJECT PROPERTIES
      • like object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • share object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Add to Calendar/Remind object

      Add to calendar/remind button action

      OBJECT PROPERTIES
      • add_calendar object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Add object

      Add button action

      OBJECT PROPERTIES
      • add object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Save object

      Save button action

      OBJECT PROPERTIES
      • save object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Follow/Save object

      Follow/Save button action

      OBJECT PROPERTIES
      • follow object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • save object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Rate object

      Rate button action

      OBJECT PROPERTIES
      • rate object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Rate/Remind object

      Rate/remind button action

      OBJECT PROPERTIES
      • rate object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • remind object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Search object

      Search button action

      OBJECT PROPERTIES
      • search object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Book object

      Book button action

      OBJECT PROPERTIES
      • book object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Happy/Sad object

      Happy/Sad button action

      OBJECT PROPERTIES
      • happy object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • sad object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

    • Up/Down object

      Up/down button action

      OBJECT PROPERTIES
      • down object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

      • up object<Actions>

        Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using Handlebars.

  • type stringREQUIRED

    A string that specifies the name of either a predefined or a custom-defined interactive notification type. Predefined types are prefixed with ua_.

    Possible values: ua_yes_no_foreground, ua_yes_no_background, ua_accept_decline_foreground, ua_accept_decline_background, ua_shop_now, ua_buy_now, ua_follow, ua_opt_in, ua_unfollow, ua_opt_out, ua_opt_in_remind, ua_remind_me_later, ua_more_info, ua_download, ua_share, ua_download_share, ua_remind_share, ua_opt_in_share, ua_opt_out_share, ua_follow_share, ua_unfollow_share, ua_shop_now_share, ua_buy_now_share, ua_more_like_less_like, ua_like_dislike, ua_like, ua_like_share, ua_add_calendar_remind, ua_add, ua_save, ua_follow_save, ua_rate, ua_rate_remind, ua_search, ua_book, ua_icons_happy_sad, ua_icons_up_down, <custom_defined_interactive_notification_type>

Used in:

Examples

Example with `type` actions

{
   "interactive": {
      "type": "ua_yes_no_foreground",
      "button_actions": {
         "yes": {
            "add_tag": "more_cake_please",
            "remove_tag": "lollipop",
            "open": {
               "type": "url",
               "content": "http://www.urbanairship.com"
            }
         },
         "no": {
            "add_tag": "nope"
         }
      }
   }
}

Example with `ua_share` actions

{
   "interactive": {
      "type": "ua_share",
      "button_actions": {
         "share": { "share": "Look at me! I'm on a boat." }
      }
   }
}

iOS channel object

Contains parameters that apply when the device_type is set to ios.

OBJECT PROPERTIES
  • badge integer

    The iOS badge number. Must be greater than zero.

  • quiettime object

    Quiet time settings. Requires presence of tz.

    OBJECT PROPERTIES
    • end string

      Quiet time end in HH:MM format.

    • start string

      Quiet time start in HH:MM format.

  • scheduled_summary boolean

    If true, the scheduled summary notification status is enabled.

  • time_sensitive boolean

    If true, the time sensitive notification status is enabled.

  • tz string

    The channel’s time zone. A list of possible time zone values is maintained at the IANA Time Zone Database .

Used in:

Landing page content

One of
  • OBJECT PROPERTIES
    • url stringREQUIRED

      The URL to be opened as a landing page. This value supports http or https schemes and can be personalized using handlebars expressions.

  • All of
    • OBJECT PROPERTIES
      • content_encoding string

        A string specifying the encoding of the text in the body attribute. Defaults to utf-8.

        Possible values: utf-8, base64

      • content_type stringREQUIRED

        A non-blank string, which must be a MIME type.

List ID

A list ID that contains only alphanumeric characters, underscores, or hyphens.

Used in:

List response object

Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

Jump to examples ↓

OBJECT PROPERTIES
  • channel_count integer

    A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.

  • created string

    The date-time when the list was initially created.

  • description string

    An optional description for the list.

  • error_path string

    If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.

  • extra object

    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.

  • last_updated string

    The date-time when the identifiers of the list were last updated successfully.

  • name stringREQUIRED

    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.

  • status string

    A string value representing the state of the list.

    • ready — The list was processed successfully and is ready for sending.
    • processing — The list is being processed.
    • failure — There was an error processing the last uploaded list.

    Possible values: ready, processing, failure

Used in:

Examples

List response object

{
  "ok": true,
  "lists": [
      {
        "name": "ua_attributes_my_list",
        "description": "My first list",
        "extra": {
            "filename": "list.csv",
            "source": "crm"
        },
        "created": "2020-05-13T21:41:25",
        "last_updated": "2020-05-13T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_my_list/errors",
        "status": "ready"
      },
      {
        "name": "ua_attributes_another_list",
        "description": "My second list",
        "extra": {
            "filename": "list2.csv",
            "source": "api"
        },
        "created": "2020-05-14T21:41:25",
        "last_updated": "2020-05-14T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_another_list/errors",
        "status": "ready"
      }
  ]
}

Localization object

An object used to indicate that message content delivered to a device should be customized for a specific locale subset. Each localization object must have at least one of country and language. Which of those two fields are present does not need to be consistent across localizations.

In addition, each localization object must have one of notification, message, or in_app set. If the top level notification, message, or in_app fields are set, they will be delivered to any user in the audience not matching any of the localizations.

Jump to examples ↓

OBJECT PROPERTIES
  • country string

    The ISO 3166-2 two-letter country code for this localization.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • language string

    The ISO 639-1 two-letter language code for this localization.

  • message object<Message Center object>

    A Message Center message.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

Used in:

Examples

Example array of localizations

{
  "localizations": [
      {
         "language": "de",
         "country": "AT",
         "notification": {
            "alert": "Grüss Gott"
         }
      },
      {
         "language": "de",
         "country": "DE",
         "notification": {
            "alert": "Guten Tag"
         }
      }
   ]
}

Message Center object

A Message Center message.

Jump to examples ↓

OBJECT PROPERTIES
  • body stringREQUIRED

    The body of the message.

  • content_encoding string

    A string denoting encoding type of the data in body. Defaults to utf-8. base64 encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded javascript code, which itself may contain embedded JSON data.

  • content_type string

    A string denoting the MIME type of the data in body. Defaults to text/html.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • 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.

  • icons object

    A JSON dictionary of string key and value pairs representing icons. At this time, only the list_icon key is supported. Values must be URI/URLs to icon resources. For resources hosted by UA, use the following URI format ua:<resource_id>.

    OBJECT PROPERTIES
    • list_icon string
  • title stringREQUIRED

    The title of the message.

Used in:

Examples

Message object example

{
   "audience": "all",
   "notification": {
      "ios": {
         "badge": "+1"
      }
   },
   "message": {
      "title": "This week's offer",
      "body": "<html><body><h1>blah blah</h1> etc...</html>",
      "content_type": "text/html",
      "expiry": "2020-04-01T12:00:00",
      "extra": {
         "offer_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "icons": {
         "list_icon": "http://cdn.example.com/message.png"
      }
   }
}

Message type

Indicates the purpose of a message.

Used in:

Notification object

The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

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 notification message, displayed for any platforms receiving the push without a platform override.

  • amazon object
    One of
    • Amazon Override Object

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

    • Amazon Override With Template

      Use a template with a Fire OS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • android object
    One of
  • email object
    One of
    • Email Override Object

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

    • Email Override With Template

      Notification fields specific to email messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • 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.

  • ios object
    One of
    • Ios Override Object

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

    • Ios Override With Template

      Use a template with iOS-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • mms object
    One of
    • Mms Override Object

      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.

    • Mms Override With Template

      Template and notification overrides for a Create and Send payload with device_types set to mms. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • open::open_platform_name object
    One of
    • Open Channel Override Object

      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.

    • Open Channel Override With Template

      Use a template with an open channel-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

  • sms object
    One of
    • Sms Override Object

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

    • Sms Override With Template

      Notification fields specific to SMS messages with an inline template for use in a Create and Send payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with {{#operator}} and end with {{/operator}}. For more information, see Handlebars.

  • web object
    One of
    • Web Override Object

      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.

    • Web Override With Template

      Use a template with a Web-specific message. You can reference a template by ID, or use {{handlebars}} directly in your message.

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

Used in:

Examples

Example notification with all platforms

{
   "audience": "all",
   "device_types": [
      "ios",
      "android",
      "amazon",
      "web",
      "email",
      "open::toaster"
   ],
   "notification": {
      "ios": {
         "alert": "Hello, iDevices"
      },
      "android": {
         "alert": "These are not the...yeah, lame joke."
      },
      "amazon": {
         "alert": "Read any good books lately?"
      },
      "web": {
         "alert": "Oh the tangled web we weave"
      },
      "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": "commercial",
         "sender_name": "Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com"
      },
      "open::toaster": {
         "alert": "Would you like avocados with that?"
      }
   }
}

Open channel options

Contains options that apply when the device_type is set to open.

OBJECT PROPERTIES
  • identifiers object

    A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.

  • old_address string

    If a channel exists for the value of old_address, replaces that channel’s address with the value of address. Use infrequently, such as when an end user’s phone number or email address permanently changes.

  • open_platform_name stringREQUIRED

    The name of the open channel that this channel_id is registered on.

Used in:

Push object

A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

Jump to examples ↓

OBJECT PROPERTIES
  • audience object<Audience selector (max 1000)>REQUIRED

    An audience selector forms the expression that determines the set of channels to target.

  • campaigns object<Campaigns object>

    An object specifying custom campaign categories related to the notification.

  • device_types array[string]REQUIRED

    An array containing one or more strings identifying targeted platforms.

  • feed_references object<Feed references object>

    An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a templates object in the payload or set the personalization option to true.

  • global_attributes object

    The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ua_. If the global attributes object is nonempty, it implies the personalization: true option.

  • in_app object<In-app message>

    A JSON object describing an in-app message payload.

  • localizations array

    An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.

  • message object
    One of
  • message_type object<Message type>

    Indicates the purpose of a message.

  • notification object<Notification object>

    The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.

  • options object<Push options>

    A JSON dictionary for specifying non-payload options related to the delivery of the push.

  • orchestration object

    An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.

    OBJECT PROPERTIES
    • channel_priority array[string]

      An array of channel types in priority order. Required if type is set to channel_priority.

    • type stringREQUIRED

      The name of the orchestration strategy to employ.

      Possible values: channel_priority, fan_out, triggering_channel, last_active

  • snippet_references object<Snippet references object>

    An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.

    See Snippets to see how to create a snippet in the Airship dashboard.

Used in:

Examples

Example push object

{
   "audience": {
      "OR": [
         {
            "tag": [
               "sports",
               "entertainment"
            ]
         },
         {
            "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
         }
      ]
   },
   "notification": {
      "alert": "Hi from Airship!{{#if super_sale }} We're having a sale on {{ products.0.name }}!{{/if}}",
      "ios": {
         "extra": {
            "url": "http://www.urbanairship.com"
         }
      }
   },
   "options": {
      "expiry": "2020-04-01T12:00:00"
   },
   "message": {
      "title": "Message title",
      "body": "<Your message here>",
      "content_type": "text/html"
   },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2020-04-01T12:00:00",
      "display": {
         "position": "top"
      }
   },
   "device_types": [ "ios", "android" ],
   "global_attributes": {
      "super_sale": true,
      "products": [
          {"id": 1, "name": "New Line Sneakers", "price": "79.95"},
          {"id": 2, "name": "Old Line Sneakers", "price": "59.95"}
      ]
   }
}

Example personalized push

{
   "device_types": [
      "sms"
   ],
   "options": {
      "personalization": true
   },
   "notification": {
      "sms": {
         "alert": "Hi {{name}}, {{#feed \"weather_updates\" kw="today" as |weather|}}It's going to be {{weather.temp}} in {{weather.loc}} today!{{/feed}}",
      }
   },
   "audience": {
      "tag": "local_updates",
      "group": "weather"
   },
   "feeds": [
      {
         "name": "weather_updates",
         "params": {
            "kw": "today"
         }
      }
   ]
}

Example localized push

{
  "device_types": [ "ios", "android" ],
  "audience": {
     "tag": "needs_a_greeting",
     "group": "new_customer"
  },
  "notification": {
     "alert": "Hi!"
  },
  "localizations": [
      {
         "language": "de",
         "country": "AT",
         "notification": {
            "alert": "Grüss Gott"
         }
      },
      {
         "language": "de",
         "country": "DE",
         "notification": {
            "alert": "Guten Tag"
         }
      }
  ]
}

Push options

A JSON dictionary for specifying non-payload options related to the delivery of the push.

OBJECT PROPERTIES
  • audience_limits object<Audience limits object>

    Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See Audience Limit in the Message delivery user guide for additional information and limitations.

  • ban_list_parameters object<Ban List parameters>

    A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a Ban List request URL.

  • bypass_ban_list_processing boolean

    If true, a user’s status on a Ban List will not be verified before sending the push.

  • bypass_frequency_limits boolean

    If true, the push ignores any Message Limits that would otherwise apply to your message.

  • bypass_holdout_groups boolean

    If true, the push ignores withholding any messages for users in a holdout group for a Holdout Experiment that is active at send time.

  • expiry object

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    One of
  • no_throttle boolean

    If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.

  • omit_from_activity_log boolean

    If true, the push is omitted from the Activity Log.

  • personalization boolean

    If true, enables Handlebars-style template syntax for eligible fields in a notification or message center objects. You can do this to enable handlebars for all available fields without using individual template objects for different platform overrides.

    This setting is implicitly true whenever your payload includes a platform override with a template object.

  • redact_payload boolean

    If true, the push payload will not appear in Airship’s logs. You cannot use this option with Message Center, A/B Tests, Automation, or Scheduled pushes, which all require the payload to be stored separately by design.

  • use_strict_sms_validation boolean

    This field is only compatible for Create and Send requests targeting SMS and MMS device_types.

    If true, Create and Send requests containing any selector entries that would result in silent row drops will return a 400 Bad Request response code. Detailed error messages will be returned for all invalid rows.

    If false, requests that contain row entries with silent errors as documented for the targeted required selector fields will return a 200 status code. However, all invalid entries will be silently dropped during request processing.

    By default, this attribute is implicitly set to false unless every entry in the request would be dropped silently as determined by the targeted selector type, at least one malformed JSON error is found in the request, or at least one validation error is encountered for a required selector field that is not documented to handle invalid data with silent drops.

Used in:

Reset action object

A Channel Contact operation using this object is mostly equivalent to Named Users disassociation, but instead of leaving the channel disassociated, it associates the channel to a new Anonymous Contact after disassociation from the current Contact.

Jump to examples ↓

OBJECT PROPERTIES
  • type stringREQUIRED

    The action to be carried out.

    Possible values: reset

Examples

Example reset contact operation

{
  "device_info": {
    "device_type": "android"
  },
  "action": {
    "type": "reset"
  }
}

Resolve action object

A Channel Contact operation using this object results in either resolving the current associated Contact (named or anonymous) for that channel or it will associate that channel to an Anonymous Contact, always returning a Contact ID for the SDK to store. A Contact ID can optionally be provided, which the channel will be associated to in the event the channel is not already associated to a Contact and the provided Contact ID is not already bound to a Named User.

Jump to examples ↓

OBJECT PROPERTIES
  • contact_id string

    Contact ID to associate to the channel if it is not already associated to a Contact.

  • type stringREQUIRED

    The action to be carried out.

    Possible values: resolve

Examples

Example resolve contact operation

{
  "device_info": {
    "device_type": "ios"
  },
  "action": {
    "type": "resolve"
  }
}

Scopes

The channel types where membership applies. The app scope includes iOS, Android, and Amazon channels.

Used in:

Sender ID

A sender_id describes the sender target to apply the keyword action event to. This must be a number the app is already configured to send from. If a sender exists in multiple countries, a country can be specified by prefixing the country code with a colon, e.g., US:12345.

The sender_id is composed of two parts:

  • A sender stem - Required numeric string.
  • A country_code - Optional 2-letter ISO 3166 country code.

SMS channel associated by contact

An SMS channel associated with a contact.

Jump to examples ↓

OBJECT PROPERTIES
  • channel_id string

    The unique identifier.

  • msisdn string

    The phone number corresponding to the channel.

  • opt_in boolean

    If true, the channel is opted in to push notifications. If false, it is not.

  • sender string

    The sender corresponding to the channel.

  • type string

    The channel type.

    Possible values: sms

Examples

Example

{
  "type": "sms",
  "channel_id": "a537ac78-ef4f-4f74-8536-6fd620549186",
  "sender": "1234",
  "msisdn": "*******3379",
  "opt_in": true
}

Snippet references object

An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.

See Snippets to see how to create a snippet in the Airship dashboard.

Jump to examples ↓

OBJECT PROPERTIES
  • snippets array[object]REQUIRED

    An array of snippets that you want to use to personalize your message.

Used in:

Examples

Example push snippets request

POST /api/push HTTP/1.1
Authorization: Basic <Master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

 {
    "device_types": ["ios"],
    "audience": { "tag": "earlyBirds" },
    "notification": {
       "alert": "Hello, {{user}}, how are you today?{{> \"signoff\" }}"
    },
    "options": {
       "personalization": true
    },
    "snippet_references": {
       "snippets": [
          {
             "name": "signoff"
          }
       ]
    }
 }

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
Content-Length: 123
Data-Attribute: push_ids

 {
    "ok": true,
    "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80",
    "push_ids": [
       "bf28d158-fefe-475a-9c2a-ed4f69cc891e"
    ]
 }

Snippet references example: The `copyright` snippet is loaded by the `snippet_references` object and inserted at the end of the `alert` text.

{
   "notification": {
      "alert": "Hi {{ name }}: Thanks for your purchase! {{> copyright }}"
   },
   "snippet_references": {
      "snippets": [
         {
            "name": "copyright"
         }
      ]
   }
}