Create messaging channels, manage members, and control channel lifecycle on Sui.
Channels in `@mysten/messaging` are on-chain objects that group participants for structured conversations. You create a channel using `client.createChannel()`, passing in a `ChannelOptions` object. Each channel gets a unique on-chain ID that you use for all subsequent operations like sending messages or managing members.
The `ChannelOptions` interface gives you full control over channel creation. The `name` field is required and acts as a human-readable label. `description` provides context. `members` is an array of Sui addresses to add at creation time. The `encrypted` flag enables end-to-end encryption for all messages in the channel using shared key derivation.
Every channel has a unique Sui object ID (a 32-byte hex string like `0x1a2b...`). You use this ID to reference the channel in all operations: sending messages, adding members, archiving, and querying. Store channel IDs in your application state. You can also look up channels by calling `client.getChannel(channelId)` to retrieve its current state.
After creating a channel, you can add new members with `client.addMembers()`. Pass in the channel ID and an array of Sui addresses. Only the channel creator (or addresses with admin permissions) can add members. The method returns a transaction result so you can confirm the operation succeeded on-chain.
Remove members with `client.removeMembers()` - same pattern as adding. To see who is in a channel, call `client.getChannelMembers()` which returns an array of member objects with their addresses and join timestamps. Only admins can remove members, and the channel creator cannot be removed.
Channels enforce a simple permission model on-chain. The creator is automatically an `admin`. Admins can add/remove members, update channel info, and archive the channel. Regular `member` roles can only send and read messages. You can promote a member to admin with `client.setMemberRole()`. Permissions are enforced by the Move smart contract, so they cannot be bypassed client-side.
When a channel is no longer needed, archive it with `client.archiveChannel()`. Archived channels become read-only: no new messages can be sent, and no members can be added. However, existing messages remain accessible for historical reference. Only admins can archive a channel. Archiving is a soft-delete - the on-chain object persists but its state changes to `archived`.
Channels have two states: `active` (default, fully functional) and `archived` (read-only). Check a channel's state with `channel.status`. Best practices: use descriptive names and descriptions for discoverability, keep member lists small for performance, archive old channels rather than deleting members, and use encrypted channels for sensitive topics. Store channel IDs in your app's database for quick lookups.