Channels

Schemas for channel management, including channel objects, registration, updates, and channel associations.

Channel listing object

Describes a channel listing object.

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

{
   "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"
   }
}

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

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

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:

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:

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

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