> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Role Management

> Add and remove chat channel roles with the current SDK APIs.

Use channel roles when selected members need elevated channel permissions, such as moderator behavior. Role names are app-defined or configured for your social.plus project; the SDK applies or removes the role for the listed channel members.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| - | - | - | - | - |
| Add role | `ChannelRepository.Moderation.addRole(channelId, roleId, userIds)` | `AmityChannelModeration(channelId:).addRole(_:userIds:)` | `moderation(channelId).addRole(role, userIds)` | `moderation(channelId).addRole(role, userIds)` |
| Remove role | `ChannelRepository.Moderation.removeRole(channelId, roleId, userIds)` | `AmityChannelModeration(channelId:).removeRole(_:userIds:)` | `moderation(channelId).removeRole(role, userIds)` | `moderation(channelId).removeRole(role, userIds)` |
| Result | `Promise<boolean>` | `Void` | `Completable` | `Future` |

## Parameters

| Parameter | Required | Description |
| - | - | - |
| `channelId` | Yes | Channel ID where the role should be changed. |
| `role` / `roleId` | Yes | Role ID to add or remove, such as `moderator` or another role configured for your app. |
| `userIds` | Yes | One or more member user IDs. Empty lists are rejected. |
| Moderation permission | Yes | The current user must have permission to manage roles in the target channel. |

## Add A Role

Add a role when channel members should receive the permissions represented by that role.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ChannelRepository } from '@amityco/ts-sdk';

  const didAddRole = await ChannelRepository.Moderation.addRole(
    channelId,
    'moderator',
    [userId],
  );

  if (didAddRole) {
    showSuccessMessage(channelId);
  }
  ```

  ```swift iOS theme={null}
  let moderation = AmityChannelModeration(channelId: channelId)

  try await moderation.addRole("moderator", userIds: [userId])

  showSuccessMessage(channelId)
  ```

  ```kotlin Android theme={null}
  val disposable = channelRepository
      .moderation(channelId = channelId)
      .addRole(role = "moderator", userIds = listOf(targetUserId))
      .subscribe(
          { showSuccessMessage(channelId) },
          { error -> handleGeneralError(error) },
      )
  ```

  ```dart Flutter theme={null}
  await AmityChatClient.newChannelRepository()
      .moderation(channelId)
      .addRole('moderator', [targetUserId]);
  ```
</CodeGroup>

## Remove A Role

Remove a role when members should no longer have the permissions represented by that role.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ChannelRepository } from '@amityco/ts-sdk';

  const didRemoveRole = await ChannelRepository.Moderation.removeRole(
    channelId,
    'moderator',
    [userId],
  );

  if (didRemoveRole) {
    showSuccessMessage(channelId);
  }
  ```

  ```swift iOS theme={null}
  let moderation = AmityChannelModeration(channelId: channelId)

  try await moderation.removeRole("moderator", userIds: [userId])

  showSuccessMessage(channelId)
  ```

  ```kotlin Android theme={null}
  val disposable = channelRepository
      .moderation(channelId = channelId)
      .removeRole(role = "moderator", userIds = listOf(targetUserId))
      .subscribe(
          { showSuccessMessage(channelId) },
          { error -> handleGeneralError(error) },
      )
  ```

  ```dart Flutter theme={null}
  await AmityChatClient.newChannelRepository()
      .moderation(channelId)
      .removeRole('moderator', [targetUserId]);
  ```
</CodeGroup>

## Implementation Notes

<CardGroup cols={2}>
  <Card title="Role IDs" icon="key">
    Pass the role ID string exactly as configured for your project. The SDK does not create new role definitions from this call.
  </Card>

  <Card title="Existing Members" icon="user-check">
    Assign roles to users who are channel members. Query the member list first when your UI needs to confirm eligibility.
  </Card>

  <Card title="Permissions" icon="shield">
    Role operations require moderation permission and can fail if the current user cannot manage the target role.
  </Card>

  <Card title="Channel Fit" icon="layer-group">
    Role moderation is meaningful on channel types that support member roles. Unsupported channel types can reject the request.
  </Card>
</CardGroup>

## Related Topics

<CardGroup cols={3}>
  <Card title="Member Management" href="./member-management" icon="users">
    Add users before assigning channel roles.
  </Card>

  <Card title="Query Members" href="/social-plus-sdk/chat/conversation-management/members/query-members" icon="list-filter">
    Filter members by role and membership state.
  </Card>

  <Card title="Ban Management" href="./ban-management" icon="user-slash">
    Restrict access for users who should not participate.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.