Channels & Conversations

SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter

Speed run — just the code

// Create a Community channel
const channel = await ChannelRepository.createChannel({
  type: 'community',
  displayName: 'General',
  isPublic: true,
  tags: ['team', 'general'],
});

// Query channels the current user is in
const liveCollection = ChannelRepository.getChannels({
  sortBy: 'lastActivity',
  includeDeleted: false,
});
liveCollection.on('dataUpdated', (channels) => renderChannelList(channels));

// Join a channel
await ChannelRepository.joinChannel(channelId);

Full walkthrough below ↓

Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.

Channels are the container for every chat conversation in social.plus. There are three types — Community (public/discoverable), Live (broadcast events), and Conversation (private 1:1 or small group). This guide covers creating and managing all three.

Data Model

Prerequisites: SDK installed with authenticated users → SDK Setup

Quick Start: Create and Join a Channel

import { ChannelRepository } from '@amityco/ts-sdk';

try {
  // Create a public Community channel
  const { data: channel } = await ChannelRepository.createChannel({
    type: 'community',
    displayName: 'General',
    isPublic: true,
  });

  // Join it
  await ChannelRepository.joinChannel(channel.channelId);
} catch (error) {
  console.error('Channel operation failed:', error);
}

Step-by-Step Implementation

Choose the right channel type

Type	Use case	Visibility
`community`	Team rooms, Discord-style, community chat	Public or Private
`live`	Livestream chat, event commentary	Public
`conversation`	1:1 DMs, customer support	Private

→ Channel Types

Create the channel

import { ChannelRepository } from '@amityco/ts-sdk';

// Community channel
const { data: channel } = await ChannelRepository.createChannel({
  type: 'community',
  displayName: 'Product Feedback',
  isPublic: true,
  tags: ['feedback', 'product'],
  metadata: { category: 'support' },
});

// Conversation (1:1 DM) — use the other user's ID as channel ID
const { data: dm } = await ChannelRepository.createChannel({
  type: 'conversation',
  userIds: ['user-123', 'user-456'],
});

→ Create Channel

Query the channel list with Live Collections

import { ChannelRepository } from '@amityco/ts-sdk';

const liveCollection = ChannelRepository.getChannels({
  filter: 'member',       // channels the current user is in
  sortBy: 'lastActivity', // most recently active first
});

// Re-renders whenever a new message arrives or channel is added
liveCollection.on('dataUpdated', (channels) => {
  channels.forEach(channel => {
    console.log(channel.displayName, channel.lastActivity);
  });
});

→ Query Channels

Join and leave channels

// Join
await ChannelRepository.joinChannel(channelId);

// Leave
await ChannelRepository.leaveChannel(channelId);

// Query members
const members = ChannelRepository.Membership.getMembers({ channelId, limit: 20 });

→ Join/Leave Channel

Update and archive channels

// Update display name and metadata
await ChannelRepository.updateChannel(channelId, {
  displayName: 'New Name',
  metadata: { archived_reason: null },
});

// Archive (hides from list but keeps message history)
// archiving: set archived_reason in metadata (no dedicated archive method in v6)

→ Update Channel · Archive Channels

Connect to Moderation & Analytics

Channel moderation from Admin Console

Community channels and their members can be reviewed and managed from Admin Console → Channels. Moderators can view message history, ban members, and close channels.→ Channel Moderation

Webhook: channel events

Subscribe to channel.created, channel.updated, and channel.deleted webhook events to sync channel data with your own backend or trigger automations.→ Webhook Events

Common Mistakes

Creating duplicate Conversation channels — For 1:1 DMs, always check if a conversation already exists between two users before creating a new one. Pass both userIds and the SDK will return the existing channel if one exists.

Not handling the Live Collection’s dispose — Always call liveCollection.dispose() when your UI component unmounts to avoid memory leaks and stale update callbacks.

Best Practices

Use Live Collections for the channel list

Don’t poll for channel updates. Live Collections push updates automatically — new messages, new channels, and member changes all arrive without any extra requests.

Store custom data in metadata

Use the metadata field to attach any application-specific data to a channel (event ID, category, feature flags). Keep it under 500KB.

Archive instead of delete

Archiving preserves message history — users who rejoin can read old messages. Hard deletion is permanent. Default to archive unless regulatory requirements mandate deletion.

Dive deeper: Conversation Management API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

Next Steps

Sending Messages

Start sending and receiving messages in the channels you just created.

Channel Roles & Permissions

Set up moderator roles before your community grows.

Unread Counts

Add unread badges to your channel list.

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

Channels & Conversations

Data Model

Quick Start: Create and Join a Channel

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps

Sending Messages

Channel Roles & Permissions

Unread Counts

​Data Model

​Quick Start: Create and Join a Channel

​Step-by-Step Implementation

​Connect to Moderation & Analytics

​Common Mistakes

​Best Practices

​Next Steps

Sending Messages

Channel Roles & Permissions

Unread Counts

Data Model

Quick Start: Create and Join a Channel

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps