# Channels

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


## Channel listing object {#channellistingobject}

Describes a channel listing object.

[Jump to examples ↓](#channellistingobject-examples)

- **`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`.

  Example: `email@example.com`

- **`alias`** `string` **DEPRECATED**

  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.

  Example: `alias_nope`

  Nullable: true

- **`attributes`** `object` <[Custom and predefined Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributes)>

  A dictionary of attributes that you've associated with the channel. See the [Attributes guide](/docs/guides/audience/attributes) 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](/docs/guides/audience/attributes/adding/).


- **`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.

  Format: `uuid`

  Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5`

- **`commercial_opted_in`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial
emails.


  Format: `date-time`

- **`commercial_opted_out`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive
commercial emails.


  Format: `date-time`

- **`created`** `string`

  The creation [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) of this channel.

  Format: `date-time`

  Read only: true

- **`device_attributes`** `object` <[Device Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#device_attributes)>

  Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: [Default Attributes](/docs/reference/data-collection/attributes/#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`.

  Example: `name@example.com`

- **`installed`** `boolean`

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

- **`ios`** `object` <[iOS channel object]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#ioschannelobject)>

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

- **`last_registration`** `string`

  The last registration [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) of this channel, if known.

  Format: `date-time`

  Nullable: true

  Read only: true

- **`msisdn`** `string`

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

  Max length: 15

  Example: `15035556789`

- **`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.

  Min length: 1, Max length: 128

  Example: `john_doe`

  Nullable: true

- **`open`** `object` <[Open channel options]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#openchanneloptionsobject)>

  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](/docs/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel gave permission to receive messages.

  Format: `date-time`

  Example: `2022-07-07T03:23:13`

- **`opt_out_date`** `string`

  `(SMS only)` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel opted out of receiving messages.

  Format: `date-time`

  Example: `2022-07-08T03:23:13`

- **`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`.

  Example: `FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660`

  Nullable: true

- **`subscription_lists`** `array` <[Subscription List object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistobject)>

  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]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)>

  One or more tag group objects (including [Device Property Tags](/docs/reference/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](/docs/reference/data-collection/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.

  Min items: 0, Max items: 1000

  Example: `Federer fan,Messi fan`

- **`transactional_opted_in`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) 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.


  Format: `date-time`

- **`transactional_opted_out`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive
transactional emails.


  Format: `date-time`

- **`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:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)

**Examples**

*Example iOS channel*

```json
{
   "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 {#emailchannelassociatedbycontactobject}

An email channel associated with a Contact.

[Jump to examples ↓](#emailchannelassociatedbycontactobject-examples)

- **`channel_id`** `string`

  The unique identifier.

  Format: `uuid`

- **`commercial_opted_in`** `string`

  The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial
emails.


  Format: `date-time`

- **`email_address`** `string`

  The email address corresponding to the channel.

- **`type`** `string`

  The channel type.

  Possible values: `email`


**Examples**

*Example*

```json
{
  "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 {#ioschannelobject}

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

- **`badge`** `integer`

  The iOS badge number. Must be greater than zero.

  Format: `int32`

- **`quiettime`** `object`

  Quiet time settings. Requires presence of `tz`.

  **OBJECT PROPERTIES**

  - **`end`** `string`

    Quiet time end in `HH:MM` format.

    Example: `07:30`

    Nullable: true

  - **`start`** `string`

    Quiet time start in `HH:MM` format.

    Example: `21:30`

    Nullable: true

- **`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](http://www.iana.org/time-zones).

  Example: `America/Los_Angeles`

  Nullable: true


**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)

---

## Open channel options {#openchanneloptionsobject}

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

- **`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.

  Example: `[object Object]`

- **`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`** `string` **REQUIRED**

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

  Example: `Slack`


**Used in:**

- [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels)
- [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel)
- [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel)
- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)
- [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel)

---

## SMS channel associated by Contact {#smschannelassociatedbycontactobject}

An SMS channel associated with a Contact.

[Jump to examples ↓](#smschannelassociatedbycontactobject-examples)

- **`channel_id`** `string`

  The unique identifier.

  Format: `uuid`

- **`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*

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

```

---