Channels & Conversations

Create and manage Community, Live, and Conversation channels — the building blocks of every chat experience.

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

1. 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

2. 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

3. 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

4. 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

5. 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.