# API

**Kind**: interface | **Module**: [Channels](https://docs.interop.io/browser/reference/javascript/channels/index.md) | **Access**: `io.channels`

**Source**: https://docs.interop.io/browser/reference/javascript/channels/api/index.html

Channels API.

## Properties

- **`mode`** (`Mode`, required) default: `"single"` *(since io.Connect Browser 3.5)*
  Retrieves the current Channel mode (single or multi Channel). Set by the io.Connect framework based on configuration.

## Methods

### add

Adds a new Channel.

```ts
(info: ChannelDefinition) => Promise<ChannelContext>
```

**Parameters**

- **`info`** (`ChannelDefinition`, required)
  Initial Channel context.

**Returns**: `Promise<ChannelContext>`

### all

Returns a list of all channel names.

```ts
() => Promise<string[]>
```

**Returns**: `Promise<string[]>` - Promise that resolves with the list of all channel names.

### clearChannelData

Clears the context data of the current Channel. The `data` property of the Channel context is set to an empty object.
Pass a Channel name as an argument to clear the data of a specific Channel.

*Since: io.Connect Browser 4.0*

```ts
(name?: string) => Promise<void>
```

**Parameters**

- **`name`** (`string`, optional)
  Name of the Channel whose context data to clear.

**Returns**: `Promise<void>`

### get

Returns the context of a given channel.

```ts
(name: string, options?: FDC3Options) => Promise<ChannelContext>
```

**Parameters**

- **`name`** (`string`, required)
  The name of the channel whose context to return.
- **`options`** (`FDC3Options`, optional)
  Settings for retrieving an FDC3 context published in the io.Connect Channel.

**Returns**: `Promise<ChannelContext>` - Promise that resolves with the context of the given channel.

### getMy

Retrieves the context of the current Channel.
It's recommended to use the `getMyChannels()` method instead, which can retrieve the contexts of the currently joined Channels both in single and in multi Channel mode.

```ts
(options?: FDC3Options) => Promise<ChannelContext | undefined>
```

**Parameters**

- **`options`** (`FDC3Options`, optional)
  Settings for retrieving an FDC3 context published in the io.Connect Channel.

**Returns**: `Promise<ChannelContext | undefined>`

### getMyChannels

Retrieves a list with the contexts of the current Channels. Can be used both in single and in multi Channel mode.
If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.

*Since: io.Connect Browser 3.5*

```ts
(options?: FDC3Options) => Promise<ChannelContext[]>
```

**Parameters**

- **`options`** (`FDC3Options`, optional)
  Settings for retrieving FDC3 contexts published in the io.Connect Channels. *Available since io.Connect Browser 4.5.*

**Returns**: `Promise<ChannelContext[]>`

### getRestrictions

Retrieves the restrictions applied to the current window for publishing or subscribing to Channels. Pass a window ID to retrieve the restrictions for the specified window.

*Since: io.Connect Browser 3.3*

```ts
(windowId?: string) => Promise<Restrictions>
```

**Parameters**

- **`windowId`** (`string`, optional)
  ID of the window for which to retrieve the applied restrictions for publishing or subscribing to Channels.

**Returns**: `Promise<Restrictions>`

### getWindowsOnChannel

Retrieves all windows on a specified Channel.

```ts
(channel: string) => Promise<IOConnectBrowser.Windows.WebWindow[]>
```

**Parameters**

- **`channel`** (`string`, required)
  The name of the Channel for which windows should be returned.

**Returns**: `Promise<IOConnectBrowser.Windows.WebWindow[]>` - Promise that resolves with the list of all windows on a specified Channel.

### getWindowsWithChannels

Retrieves all windows that can use Channels together with their current Channel.

```ts
(filter?: WindowWithChannelFilter) => Promise<WindowOnChannelInfo[]>
```

**Parameters**

- **`filter`** (`WindowWithChannelFilter`, optional)
  Filter describing which windows to retrieve. If no filter is supplied, will return all windows that can use Channels.

**Returns**: `Promise<WindowOnChannelInfo[]>` - Promise that resolves with the list of all windows that can use Channels together with their current Channel.

### join

Joins a new channel by name. Leaves the current channel.

```ts
(name: string, windowId?: string) => Promise<void>
```

**Parameters**

- **`name`** (`string`, required)
  The name of the channel to join.
- **`windowId`** (`string`, optional)
  ID of a window which to join to a Channel. If not provided, will join the current window to the specified Channel.

**Returns**: `Promise<void>` - Promise that resolves when the channel has been joined.

### leave

Removes the current or a specified window from the current or a specified Channel.
If you don't provide an argument, the current window will be removed from the current Channel if in single Channel mode,
or from all currently joined Channels if in multi Channel mode.

```ts
(options?: string | LeaveOptions) => Promise<void>
```

**Parameters**

- **`options`** (`string | LeaveOptions`, optional)
  Object with options which you can use to remove any window from any Channel,
  or a string with the ID of a window to remove from the currently joined Channel or Channels.

**Returns**: `Promise<void>`

### list

Returns a list of all channel contexts.

```ts
() => Promise<ChannelContext[]>
```

**Returns**: `Promise<ChannelContext[]>` - Promise that resolves with the list of all channel contexts.

### my

Retrieves the name of the current Channel.
It's recommended to use the `myChannels()` method instead, which can retrieve the names of the currently joined Channels both in single and in multi Channel mode.

```ts
() => string
```

**Returns**: `string`

### myChannels

Retrieves a list with the names of the current Channels. Can be used both in single and in multi Channel mode.
If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.

*Since: io.Connect Browser 3.5*

```ts
() => string[]
```

**Returns**: `string[]`

### onChanged

Notifies when the current window joins or leaves a Channel. Returns an unsubscribe function.
It's recommended to use the `onChannelsChanged()` method instead, which can handle Channel changes both in single and in multi Channel mode.

```ts
(callback: (channel: string) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(channel: string) => void`, required)
  Callback function for handling the event. Receives as an argument the name of the newly joined Channel. If the window leaves a Channel without joining a new one, the argument will be `undefined`.

**Returns**: `UnsubscribeFunction`

### onChannelsChanged

Notifies when the current window joins or leaves a Channel. Can be used both in single and in multi Channel mode.
If used in single Channel mode, when the window joins a Channel, the array argument passed to the callback for handling the event
will always contain a single member; when the window leaves the current Channel, the array will be empty. Returns an unsubscribe function.

*Since: io.Connect Browser 3.5*

```ts
(callback: (channels: string[]) => void) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(channels: string[]) => void`, required)
  Callback function for handling the event. Receives a list with the names of the currently joined Channels as an argument.

**Returns**: `UnsubscribeFunction`

### publish

Updates the context of the current or a given channel.

```ts
(data: any, options?: string | PublishOptions) => Promise<void>
```

**Parameters**

- **`data`** (`any`, required)
  Data object with which to update the channel context.
- **`options`** (`string | PublishOptions`, optional)
  The name of the Channel to update, or an object containing the name of the Channel to update and a flag indicating whether the published data is an FDC3 context. If no options are provided, the current Channel will be updated.

**Returns**: `Promise<void>` - Promise that resolves when the data has been published.

### remove

Removes a Channel.

```ts
(name: string) => Promise<void>
```

**Parameters**

- **`name`** (`string`, required)
  The name of the Channel to remove.

**Returns**: `Promise<void>`

### restrict

Prevents or allows the current or another window to publish or subscribe to a specific Channel.

*Since: io.Connect Browser 3.3*

```ts
(config: ChannelRestrictions) => Promise<void>
```

**Parameters**

- **`config`** (`ChannelRestrictions`, required)

**Returns**: `Promise<void>`

### restrictAll

Prevents or allows the current or another window to publish or subscribe to all Channels.

*Since: io.Connect Browser 3.3*

```ts
(restrictions: RestrictionsConfig) => Promise<void>
```

**Parameters**

- **`restrictions`** (`RestrictionsConfig`, required)
  Restrictions for publishing or subscribing to all Channels.

**Returns**: `Promise<void>`

### setPath

Sets a specified path within the Channel context to the provided value. If the path doesn't exist, it will be created.

*Since: io.Connect Browser 4.0*

```ts
(path: IOConnectBrowser.Contexts.PathValue, name?: string) => Promise<void>
```

**Parameters**

- **`path`** (`IOConnectBrowser.Contexts.PathValue`, required)
  Object containing the path to update and the value with which to update it. The path must be specified as a dot-separated string (e.g., `"prop1.prop2"`).
- **`name`** (`string`, optional)
  Name of the Channel to update. If not specified, will update the current Channel.

**Returns**: `Promise<void>`

### setPaths

Sets a list of specified paths within the Channel context to the provided values. If a path doesn't exist, it will be created.

*Since: io.Connect Browser 4.0*

```ts
(paths: IOConnectBrowser.Contexts.PathValue[], name?: string) => Promise<void>
```

**Parameters**

- **`paths`** (`IOConnectBrowser.Contexts.PathValue[]`, required)
  List of objects each containing a path to update and the value with which to update it. The path must be specified as a dot-separated string (e.g., `"prop1.prop2"`).
- **`name`** (`string`, optional)
  Name of the Channel to update. If not specified, will update the current Channel.

**Returns**: `Promise<void>`

### subscribe

Tracks the data in the current channel. Persisted after a channel change.
The callback isn't called when you publish the data.

```ts
(callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => UnsubscribeFunction
```

**Parameters**

- **`callback`** (`(data: any, context: ChannelContext, updaterId: string) => void`, required)
  Callback function to handle the received data.
- **`options`** (`FDC3Options`, optional)
  Settings for subscribing to an FDC3 context published in the io.Connect Channel.

**Returns**: `UnsubscribeFunction` - Unsubscribe function.

### subscribeFor

Tracks the data in a given channel.

```ts
(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => Promise<UnsubscribeFunction>
```

**Parameters**

- **`name`** (`string`, required)
  The channel to track.
- **`callback`** (`(data: any, context: ChannelContext, updaterId: string) => void`, required)
  Callback function to handle the received data.
- **`options`** (`FDC3Options`, optional)
  Settings for subscribing to an FDC3 context published in the io.Connect Channel.

**Returns**: `Promise<UnsubscribeFunction>` - Promise that resolves with an unsubscribe function.

## Related types

- [ChannelContext](https://docs.interop.io/browser/reference/javascript/channels/channelcontext/index.md)
- [ChannelDefinition](https://docs.interop.io/browser/reference/javascript/channels/channeldefinition/index.md)
- [ChannelRestrictions](https://docs.interop.io/browser/reference/javascript/channels/channelrestrictions/index.md)
- [FDC3Options](https://docs.interop.io/browser/reference/javascript/channels/fdc3options/index.md)
- [LeaveOptions](https://docs.interop.io/browser/reference/javascript/channels/leaveoptions/index.md)
- [Mode](https://docs.interop.io/browser/reference/javascript/channels/mode/index.md)
- [PathValue](https://docs.interop.io/browser/reference/javascript/shared%20contexts/pathvalue/index.md)
- [PublishOptions](https://docs.interop.io/browser/reference/javascript/channels/publishoptions/index.md)
- [Restrictions](https://docs.interop.io/browser/reference/javascript/channels/restrictions/index.md)
- [RestrictionsConfig](https://docs.interop.io/browser/reference/javascript/channels/restrictionsconfig/index.md)
- [UnsubscribeFunction](https://docs.interop.io/browser/reference/javascript/search/unsubscribefunction/index.md)
- [WebWindow](https://docs.interop.io/browser/reference/javascript/windows/webwindow/index.md)
- [WindowOnChannelInfo](https://docs.interop.io/browser/reference/javascript/channels/windowonchannelinfo/index.md)
- [WindowWithChannelFilter](https://docs.interop.io/browser/reference/javascript/channels/windowwithchannelfilter/index.md)