Use the ably channels annotations subscribe command to subscribe to annotations on an Ably Pub/Sub channel.
Synopsis
ably channels annotations subscribe <channel-name> [options]Arguments
channel-name Required
The name of the channel to subscribe to annotations on.
Options
--type
Filter annotations by type. The type is specified in the format namespace:summarization.version. The namespace is a custom string that groups related annotations, such as reactions, categories, metrics, rating etc. For example, reactions:unique.v1 or metrics:total.v1.
The following summarization methods are available:
| Method | Description |
|---|---|
total.v1 | Counts all annotations without client attribution. Unidentified clients can publish this type. |
flag.v1 | Counts distinct clients contributing once per type. Requires an identified client. |
distinct.v1 | Counts unique clients per annotation name. Each client contributes once per name. Requires an identified client. |
unique.v1 | Guarantees each client contributes to only one name at a time. Publishing a new name auto-removes the previous one. Requires an identified client. |
multiple.v1 | Tracks per-client and total counts. A client can contribute to the same annotation name multiple times. Requires an identified client. |
See the annotations documentation for more details.
--duration | -D
The duration in seconds to subscribe for before automatically unsubscribing.
--rewind
The number of annotations to rewind when subscribing. Defaults to 0.
--client-id
A client ID to use when subscribing.
--json
Output results as compact JSON. Mutually exclusive with --pretty-json.
--pretty-json
Output results in formatted JSON. Mutually exclusive with --json.
--verbose | -v
Enable verbose logging. Can be combined with --json or --pretty-json.
Examples
Subscribe to all annotations on a channel:
ably channels annotations subscribe my-channelSubscribe to annotations filtered by type:
ably channels annotations subscribe my-channel --type "reactions:unique.v1"Subscribe for a specific duration:
ably channels annotations subscribe my-channel --duration 60Subscribe to metric-type annotations on a channel:
ably channels annotations subscribe my-channel --type "metrics:total.v1"Subscribe to annotations and output events in JSON format:
ably channels annotations subscribe my-channel --jsonSee also
- Channels — Explore all
ably channelscommands. - CLI reference — Full list of available commands.