> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/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+ 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>