# Open Channels Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc.). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship. If you are sending through the [Push API](/developer/rest-api/ua/operations/push/), platform overrides for open platforms are covered in [Open Channel Overrides](/developer/rest-api/ua/schemas/platform-overrides/#openchanneloverrideobject). For open channel lookup, use the [Channel Lookup endpoint](/developer/rest-api/ua/operations/channels/#getchannel). ## Open channel tags {#modifyopenchanneltags} Manipulate a single open channel’s tags. Open channels are identified by `address`, not by their `channel_id`. [Jump to examples ↓](#modifyopenchanneltags-examples) ### `POST /api/channels/open/tags` {{< important >}} A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative. {{< /important >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): chn **Request body** **Content-Type:** `application/json` - **`add`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> 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](/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. - **`audience`** `object` **REQUIRED** The request body containing an address and `open_platform_name`. **OBJECT PROPERTIES** - **`address`** `string` **REQUIRED** 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. Example: `new_email@example.com` - **`open_platform_name`** `string` **REQUIRED** An alphanumeric string that must be the name of a pre-created open platform object. Min length: 1, Max length: 128 Example: `twitter` - **`remove`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> 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](/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. - **`set`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> 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](/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. **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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#okresponseobject) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/channels/open/tags HTTP/1.1 Authorization: Basic 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 HTTP/1.1 200 Accepted Content-Type: application/vnd.urbanairship+json; version=3 { "ok":true } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .build(); OpenChannelTagRequest openChannelTagRequest = OpenChannelTagRequest.newRequest() .addOpenChannel("Number Four","cyclon") .addTags("CRM_Delux", Set.of("tag1","tag2")) .removeTags("CRM_Delux", Set.of("tag3","tag4")); Response response = client.execute(openChannelTagRequest); ``` ```python from urbanairship import ( BasicAuthClient, OpenChannel ) client = BasicAuthClient( key='', secret='' ) channel = OpenChannel(airship=client) channel.address = 'Number Four' channel.open_platform = 'cylon' channel.tags = ['tag1', 'tag2', 'tag3'] response = channel.update() ``` ```ruby require 'urbanairship' UA = Urbanairship airship = UA::Client.new(key: '', 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 or update channel {#createorupdateopenchannel} Create a new open channel or update an existing open channel. [Jump to examples ↓](#createorupdateopenchannel-examples) ### `POST /api/channels/open` {{< note >}} A 200 status will be returned if an existing channel was found for the specified `open_platform_name` and address. Otherwise, a new channel will be created and a 200 status will be returned. {{< /note >}} {{< important >}} The master secret is required to update an open channel, otherwise a 401 Unauthorized response is returned. {{< /important >}} **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): chn **Request body** An open channel object. **Content-Type:** `application/json` - **`channel`** `object` **REQUIRED** Properties of the open channel object. **OBJECT PROPERTIES** - **`address`** `string` **REQUIRED** 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. Example: `+1 5558675309` - **`locale_country`** `string` The two-letter country locale short code. Will set the `ua_locale_country` tag group to the specified value. Example: `US` - **`locale_language`** `string` The two-letter language locale short code. Will set the `ua_locale_language` tag group to the specified value. - **`open`** `object` **REQUIRED** 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. Max items: 100 Example: `[object Object]` - **`open_platform_name`** `string` **REQUIRED** The name of the open platform to which you are registering this channel. Example: `slack` - **`opt_in`** `boolean` **REQUIRED** 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. Min items: 1, Max items: 1000 Example: `one_tag,two_tag,red_tag,blue_tag` - **`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. Example: `America/Los_Angeles` - **`type`** `string` **REQUIRED** 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: | Name | Type | Description | |------|------|-------------| | `Location` | `string` | Used for later API calls for this channel. | Response body: **Content-Type:** `application/json` - **`channel_id`** `string` Identifies the new open channel or the open channel you successfully updated. Format: `uuid` Example: `ef625038-70a3-41f1-826f-57bc11dd625a` - **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/channels/open HTTP/1.1 Authorization: Basic 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 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" } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .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 response = client.execute(request); ``` ```python from urbanairship import ( BasicAuthClient, OpenChannel ) client = BasicAuthClient( key='', 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() ``` ```ruby require 'urbanairship' UA = Urbanairship airship = UA::Client.new(key: '', 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 {#uninstallopenchannels} 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 ↓](#uninstallopenchannels-examples) ### `POST /api/channels/open/uninstall` **Security:** - [basicAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-basicAuth) - [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth) - [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): chn **Request body** An `address` and the `open_platform_name` you want to uninstall the address from. **Content-Type:** `application/json` - **`address`** `string` **REQUIRED** 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. Example: `new_email@example.com` - **`open_platform_name`** `string` **REQUIRED** An alphanumeric string that must be the name of a pre-created open platform object. Min length: 1, Max length: 128 Example: `twitter` **Responses** **`202`** The request has been accepted for processing. Response body: **Content-Type:** `application/json` [OK response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#okresponseobject) **`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]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing. Response body: **Content-Type:** `text/plain` [Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error) **Examples** *Example* ```http POST /api/channels/open/uninstall HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "address": "Number Four", "open_platform_name": "cylon" } ``` ```http HTTP/1.1 202 Accepted Content-Type: application/vnd.urbanairship+json; version=3 { "ok": true } ``` ```java UrbanAirshipClient client = UrbanAirshipClient.newBuilder() .setKey("") .setSecret("") .build(); OpenChannelUninstallRequest openChannelUninstallRequest = OpenChannelUninstallRequest.newRequest("Number Four","cyclon"); Response response = client.execute(openChannelUninstallRequest); ``` ```python from urbanairship import ( BasicAuthClient, OpenChannel ) client = BasicAuthClient( key='', secret='' ) channel = OpenChannel(airship=client) channel.address = 'Number Four' channel.open_platform = 'cylon' response = channel.uninstall() ``` ```ruby require 'urbanairship' UA = Urbanairship airship = UA::Client.new(key: '', secret: '') cu = UA::OpenChannelUninstall.new(client: airship) cu.uninstall(address: 'Number Four', open_platform: 'cylon') ``` ---