# ChannelDetails

Channel metadata describes the current state of a channel, including whether it is active and its [occupancy](https://ably.com/docs/presence-occupancy/occupancy.md) metrics. It is represented by the `ChannelDetails` type.

A realtime client receives `ChannelDetails` payloads in two ways:

- By subscribing to a [metachannel](https://ably.com/docs/metadata-stats/metadata.md) such as `[meta]channel.lifecycle`, where each message's `data` is a `ChannelDetails` object describing a channel lifecycle event.
- By subscribing to a channel with the [`occupancy` channel option](https://ably.com/docs/channels/options.md#occupancy) enabled, which delivers `[meta]occupancy` events whose `data` contains the channel's occupancy metrics.

The canonical, typed way to fetch a channel's current `ChannelDetails` on demand is the REST SDK's `channel.status()` method; over a realtime connection the same information arrives asynchronously as the events described above.

<Code>

#### Javascript

```
// Receive channel lifecycle events, each carrying a ChannelDetails payload
const metaChannel = realtime.channels.get('[meta]channel.lifecycle');
await metaChannel.subscribe((message) => {
  const details = message.data;
  console.log(details.channelId, details.status.occupancy.metrics.connections);
});

// Receive occupancy events by enabling the occupancy channel option
const channel = realtime.channels.get('your-channel-name', {
  params: { occupancy: 'metrics' },
});
await channel.subscribe('[meta]occupancy', (message) => {
  console.log(message.data.metrics);
});
```
</Code>

## ChannelDetails 

A `ChannelDetails` object contains information about a channel, along with its current state in a `ChannelStatus` object.

<Table id='ChannelDetailsProperties'>

| Property | Description | Type |
| --- | --- | --- |
| channelId | The name of the channel, including any qualifier. | String |
| status | The current state of the channel. | <Table id='ChannelStatus'/> |

</Table>

<Table id='ChannelStatus' >

| Property | Description | Type |
| --- | --- | --- |
| isActive | Whether the channel is active. For events indicating regional activity, this reflects activity in that region rather than global activity. | Boolean |
| occupancy | The occupancy of the channel. For events indicating regional activity, this reflects activity in that region rather than global activity. | <Table id='ChannelOccupancy'/> |

</Table>

<Table id='ChannelOccupancy' >

| Property | Description | Type |
| --- | --- | --- |
| metrics | The occupancy metrics for the channel. | <Table id='ChannelMetrics'/> |

</Table>

<Table id='ChannelMetrics' >

| Property | Description | Type |
| --- | --- | --- |
| connections | The number of connections attached to the channel. | Number |
| publishers | The number of connections attached to the channel that are authorized to publish. | Number |
| subscribers | The number of connections attached that are authorized to subscribe to messages. | Number |
| presenceConnections | The number of connections that are authorized to enter members into the presence set. | Number |
| presenceMembers | The number of members currently entered into the presence set. | Number |
| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | Number |

</Table>

## Example

The following is an example of a `ChannelDetails` payload:

<Code>

### Json

```
{
  "channelId": "foo",
  "status": {
    "isActive": true,
    "occupancy": {
      "metrics": {
        "connections": 1,
        "publishers": 1,
        "subscribers": 1,
        "presenceConnections": 1,
        "presenceMembers": 0,
        "presenceSubscribers": 1
      }
    }
  }
}
```
</Code>

## Related Topics

- [Channels](https://ably.com/docs/pub-sub/api/javascript/realtime/channels.md): API reference for the Channels interface in the Ably Pub/Sub JavaScript Realtime SDK.
- [RealtimeChannel](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel.md): API reference for the Channel (RealtimeChannel) interface in the Ably Pub/Sub JavaScript Realtime SDK.
- [Message](https://ably.com/docs/pub-sub/api/javascript/realtime/message.md): API reference for the Message interface in the Ably Pub/Sub JavaScript Realtime SDK.
- [RealtimeAnnotations](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-annotations.md): API reference for message annotations (the RealtimeAnnotations interface) in the Ably Pub/Sub JavaScript Realtime SDK.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.