Open Channels

Open channel tags

Manipulate a single open channel’s tags. Open channels are identified by address, not by their channel_id.

Jump to examples ↓

POST /api/channels/open/tags

Security:

Request body:

• Content-Type: application/json

  Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.

  OBJECT PROPERTIES
  • add object<Tag Group object>

    Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    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.

  • audience objectREQUIRED

    The request body containing an address and open_platform_name.

    OBJECT PROPERTIES
    • address stringREQUIRED

      Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

    • open_platform_name stringREQUIRED

      An alphanumeric string that must be the name of a pre-created open platform object.

  • remove object<Tag Group object>

    Removes the specified tags from the 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.

  • set object<Tag Group object>

    Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

    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.

Responses

• 200

  Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

  Response body:

  • Content-Type: application/vnd.urbanairship+json; version=3
    OK response

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

 {
  "audience": {
      "address": "Number Four",
      "open_platform_name": "cylon"
  },
  "add": {
    "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
  }
 }

HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok":true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannelTagRequest openChannelTagRequest =  OpenChannelTagRequest.newRequest()
        .addOpenChannel("Number Four","cyclon")
        .addTags("CRM_Delux", Set.of("tag1","tag2"))
        .removeTags("CRM_Delux",  Set.of("tag3","tag4"));
Response<GenericResponse> response = client.execute(openChannelTagRequest);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
channel.tags = ['tag1', 'tag2', 'tag3']
response = channel.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.channel_id = 'df6a6b50-9843-0304-d5a5-743f246a4946'
open_channel.tags = ['tag1', 'tag2', 'tag3']
open_channel.update(set_tags: true)

Register new / update channel

Create a new open channel or update an existing open channel.

Jump to examples ↓

POST /api/channels/open

Security:

Request body:

An open channel object.

• Content-Type: application/json

  OBJECT PROPERTIES
  • channel objectREQUIRED

    Properties of the open channel object.

    OBJECT PROPERTIES
    • address stringREQUIRED

      Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

    • locale_country string

      The two-letter country locale short code. Will set the ua_locale_country tag group to the specified value.

    • locale_language string

      The two-letter language locale short code. Will set the ua_locale_language tag group to the specified value.

    • open objectREQUIRED

      Open channel-specific properties.

      OBJECT PROPERTIES
      • identifiers object

        Optional object with string-to-string key:value pairs that represent non-segmentable identifiers for the channel in your delivery systems. Delivered as part of webhook payloads. If present, the value will overwrite (not union with) existing identifier records.

      • open_platform_name stringREQUIRED

        The name of the open platform to which you are registering this channel.

    • opt_in booleanREQUIRED

      If false, no payloads will be delivered for the channel.

    • tags array[string]

      A list of strings used for audience targeting. When used for this endpoint, operates like the tags { set {}} operation; specified tags are applied, and all other tags are removed.

    • timezone string

      An IANA tzdata identifier for the time zone as a string, e.g., "America/Los_Angeles". Will set the timezone tag group tag with the specified value.

    • type stringREQUIRED

      Required string.

      Possible values: open

Responses

• 200

  Returned if the new channel is created successfully or if an existing channel was found for the specified open_platform_name and address.

  Response headers:

  • Location string

    Used for later API calls for this channel.

  Response body:

  • Content-Type: application/json
    OBJECT PROPERTIES
    • channel_id string

      Identifies the new open channel or the open channel you successfully updated.

    • ok boolean

      Success.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 429

  Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

{
   "channel": {
      "type": "open",
      "opt_in": true,
      "address": "Number Four",
      "tags": [
         "toaster",
         "caprica"
      ],
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en",
      "open": {
         "open_platform_name": "cylon",
         "identifiers": {
            "model": "4"
         }
      }
   }
}

HTTP/1.1 200 OK
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannel openChannel = OpenChannel.newBuilder()
        .setOpenPlatformName("cylon")
        .setOldAddress("Number Four")
        .addIdentifier("model", "4")
        .build();

Channel channel = Channel.newBuilder()
        .setOpenChannel(openChannel)
        .setChannelType(ChannelType.OPEN)
        .setOptIn(true)
        .setAddress("Number Four")
        .setTags(true)
        .addTag("toaster")
        .setTimeZone("America/Los_Angeles")
        .setLocaleCountry("US")
        .setLocaleLanguage("en")
        .build();

OpenChannelPayload payload = new OpenChannelPayload(channel);
OpenChannelRequest request = OpenChannelRequest.newRequest(payload);
Response<OpenChannelResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
channel.opt_in = True
channel.tags = ['toaster', 'caprica']
channel.identifiers = {'model': '4'}
response = channel.create()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.create()

Uninstall open channels

Uninstall a channel needing to know its Channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.

Jump to examples ↓

POST /api/channels/open/uninstall

Security:

Request body:

An address and the open_platform_name you want to uninstall the address from.

• Content-Type: application/json

  Open channel identifier

  The request body containing an address and open_platform_name.

  OBJECT PROPERTIES
  • address stringREQUIRED

    Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel_id. New addresses on existing channels will overwrite old associations.

  • open_platform_name stringREQUIRED

    An alphanumeric string that must be the name of a pre-created open platform object.

Responses

• 202

  The request has been accepted for processing.

  Response body:

  • Content-Type: application/json
    OK response

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.

  Response body:

  • Content-Type: application/json
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  Response body:

  • Content-Type: text/plain
    Error response

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

{
  "address": "Number Four",
  "open_platform_name": "cylon"
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

OpenChannelUninstallRequest openChannelUninstallRequest = OpenChannelUninstallRequest.newRequest("Number Four","cyclon");
Response<GenericResponse> response = client.execute(openChannelUninstallRequest);

from urbanairship import (
    BasicAuthClient, OpenChannel
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
channel = OpenChannel(airship=client)
channel.address = 'Number Four'
channel.open_platform = 'cylon'
response = channel.uninstall()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

cu = UA::OpenChannelUninstall.new(client: airship)
cu.uninstall(address: 'Number Four', open_platform: 'cylon')