Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
import { ChannelRepository } from '@amityco/ts-sdk';

// Add a moderator role
await ChannelRepository.addRole(channelId, 'channel-moderator', [userId]);

// Remove a moderator role
await ChannelRepository.removeRole(channelId, 'channel-moderator', [userId]);

// Query members by role
const mods = ChannelRepository.getMembers({
  channelId,
  roles: ['channel-moderator'],
});
mods.on('dataUpdated', (members) => renderModeratorList(members));
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.
Channel roles let you delegate community management without giving users platform-wide admin access. A moderator can mute, ban, and delete messages. A channel owner (automatically assigned on creation) can manage roles and channel settings. Regular members can read and write, but nothing more.
Prerequisites: Community channel with at least a few members → Channels & Conversations

​
Quick Start: Promote a Member to Moderator

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

try {
  // Grant moderator privileges to a user
  await ChannelRepository.addRole(channelId, 'channel-moderator', [userId]);
} catch (error) {
  console.error('Failed to assign role:', error);
}

​
Step-by-Step Implementation

1

Understand built-in roles

RolePermissions
channel-ownerManage roles, update channel, archive, all moderator permissions
channel-moderatorBan/unban members, mute/unmute, delete any message
(member — default)Send messages, react, view members
The channel creator is automatically assigned channel-owner. There can only be one owner. To transfer ownership, remove the owner role from yourself and add it to another user.
→ Roles and Permissions Reference
2

Assign and remove roles

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

// Add moderator
await ChannelRepository.addRole(channelId, 'channel-moderator', [userId]);

// Remove moderator
await ChannelRepository.removeRole(channelId, 'channel-moderator', [userId]);

// Transfer ownership (remove from self, add to other)
await ChannelRepository.removeRole(channelId, 'channel-owner', [myUserId]);
await ChannelRepository.addRole(channelId, 'channel-owner', [newOwnerId]);
3

Query members and filter by role

// All members
const members = ChannelRepository.getMembers({ channelId });
members.on('dataUpdated', (list) =>
  list.forEach(m => console.log(m.userId, m.roles))
);

// Only moderators
const mods = ChannelRepository.getMembers({
  channelId,
  roles: ['channel-moderator', 'channel-owner'],
});
→ Query Channel Members
4

Gate moderation UI behind role checks

Check the current user’s roles before showing ban/mute buttons:
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: membership } = await ChannelRepository.getMember(channelId, currentUserId);
const canModerate = membership.roles.some(
  r => r === 'channel-moderator' || r === 'channel-owner'
);

if (canModerate) {
  showModerationControls();
}
The SDK also enforces permissions server-side — the role check in your UI is purely for UX, not security. Non-moderators receive a permission error if they somehow trigger a moderation action.
5

Create custom roles (Admin Console)

Beyond the built-in roles, you can define custom roles (e.g., vip, verified-seller) with specific permission sets in Admin Console → Roles & Permissions. Custom roles appear in member.roles exactly like built-in ones.→ Custom Roles

​
Connect to Moderation & Analytics

member.roles_added and member.roles_removed webhook events let you sync role changes with your own database or trigger downstream workflows (e.g., granting a user access to a private board after becoming a moderator).→ Webhook Events
All role assignments are logged in Admin Console → Audit Log. Use this to review who granted moderator access and when.

​
Common Mistakes

Forgetting to remove the owner role before transferring — Calling addRole for channel-owner on a new user without removing it from the current owner results in two owners, which may cause unexpected permission behavior. Always remove before adding for ownership transfer.
Checking roles only on the client — Roles are enforced server-side. Client-side checks are only for UI gating. A user who has been demoted but still has a cached role object in memory will receive a server error on their next moderation action.

​
Best Practices

Promote at least one moderator immediately after creating a channel, especially for public Community channels. Unmoderated channels fill up with spam within hours of gaining traction.
Create roles like vip or premium to give paying users or power members special UI treatment (highlighted names, extended media limits) without granting full moderation powers.
Review moderator lists quarterly. Former moderators who no longer actively participate should be demoted — stale moderator accounts are a common attack vector.
Dive deeper: Moderation & Safety API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

​
Next Steps

Chat Moderation

Use your new moderators to ban, mute, and remove content.

Group Chat Path

Full group chat build path where roles and permissions matter most.

Channels & Conversations

Back to channel management fundamentals.