Skip to main content
social.plus SDK provides comprehensive member querying capabilities enabling administrators and moderators to manage community membership through flexible filtering, role-based searches, and real-time member lists. Build powerful member management interfaces with advanced search and filtering options.

Member Filtering

Filter members by status, roles, and membership criteria

Keyword Search

Search members by display name and user ID with live results

Role Management

Query members by moderator roles and custom role assignments

Live Collections

Real-time member lists that update as membership changes
Member queries return Live Collections that automatically update when members join, leave, change status, or receive role assignments, ensuring your member management interface stays current with the latest membership data.

​
Query Community Members

The getMembers() method retrieves community members with flexible filtering and sorting options, returning a Live Collection that updates in real-time as membership changes occur.

​
Parameters

ParameterTypeRequiredDescription
communityIdStringYesUnique identifier of the community
filterEnumNoMembership status filter: .member, .banned, .all (default: .member)
rolesArrayNoFilter by specific roles (e.g., ["community-moderator"], custom role IDs)
excludingRolesArrayNoExclude members who hold any of the specified roles. Local-only filter — not sent to backend. Available on iOS and Android only.
sortByEnumNoSort order: .displayName, .firstCreated, .lastCreated (default: .firstCreated)
includeDeletedBooleanNoInclude members whose users have been deleted (default: false)

​
Filter Options

Filter TypeOptionsDescription
Membership Statusmember, banned, allControl which members are included based on ban status
Role Filteringcommunity-moderator, channel-moderator, custom role IDsQuery members with specific roles
Deleted Userstrue, falseInclude or exclude members whose user accounts are deleted
Querying banned members requires Admin role permissions. Moderators and regular users cannot access banned member lists for security reasons.
var token: AmityNotificationToken?

func getMembers(membershipOptions: AmityCommunityMembership.QueryFilter,
                roles: [String],
                sortBy: AmityCommunityMembershipSortOption) {
    
    let liveCollection = communityMembership.getMembers(
        filter: membershipOptions,
        roles: roles,
        sortBy: sortBy,
        includeDeleted: false
    )
    
    token = liveCollection.observe { collection, change, error in
        for _ in collection.allObjects() {
            // For example, to handle each member in the list.
        }
    }
    
}

​
Search Community Members

The searchMembers() method provides keyword-based member search with the same filtering and sorting capabilities as general queries, perfect for finding specific members within large communities.

​
Parameters

ParameterTypeRequiredDescription
keywordStringYesSearch term to match against display names and user IDs
communityIdStringYesUnique identifier of the community
filterEnumNoMembership status filter: .member, .banned, .all (default: .member)
rolesArrayNoFilter search results by specific roles
excludingRolesArrayNoExclude members who hold any of the specified roles. Local-only filter — not sent to backend. Available on iOS and Android only.
sortByEnumNoSort order: .displayName, .firstCreated, .lastCreated (default: .displayName)
includeDeletedBooleanNoInclude deleted users in search results (default: false)

​
Search Behavior

  • No Keyword: Returns all members sorted by join date
  • With Keyword: Returns members with matching display names or user IDs, sorted by relevance
  • Real-time Results: Search results update automatically as members change
var searchToken: AmityNotificationToken?
func searchMember(keyword: String,
                  filter: [AmityCommunityMembership.SearchFilter],
                  roles: [String],
                  sortBy: AmityCommunityMembershipSortOption) {
    
    let liveCollection = communityMembership.searchMembers(
        keyword: keyword,
        filter: filter,
        roles: roles,
        sortBy: sortBy,
        includeDeleted: false
    )
    
    token = liveCollection.observe { collection, change, error in
        for _ in collection.allObjects() {
            // List of user with related keyword.
        }
    }
    
}

​
Excluding Roles from Results

Platform Availability: The excludingRoles parameter is currently available on iOS and Android only. Web (TypeScript) support is under development.
The excludingRoles parameter lets you filter out members who hold specific roles from both getMembers() and searchMembers() results. This is useful for building member lists that exclude staff, bots, or other special-role users.
  • ANY-match semantics — A member is excluded if they hold any role from the exclusion list.
  • Combinable with roles — You can use both roles (inclusion) and excludingRoles (exclusion) together. Inclusion is applied first, then exclusion.
// Get community members excluding moderators
let liveCollection = communityMembership.getMembers(
    filter: .member,
    roles: [],
    excludingRoles: ["community-moderator", "channel-moderator"],
    sortBy: .firstCreated,
    includeDeleted: false
)

token = liveCollection.observe { collection, change, error in
    // Members list will NOT include any moderators
}
If a role appears in both roles and excludingRoles, the exclusion takes precedence — members with that role will not appear in results.

​
Role Management and Permissions

​
Default Roles

RoleIDPermissionsQuery Access
Community Moderatorcommunity-moderatorFull community managementAll members
Channel Moderatorchannel-moderatorChannel-specific moderationChannel members
MemberN/ABasic participationCannot query roles

​
Custom Roles

  • SDK Assignment: Custom roles can be assigned via SDK
  • Community Level: Roles apply only within specific communities
  • Query Support: Custom role IDs can be used in member queries
Custom roles assigned via social.plus Console apply at the user level, not community level, and won’t appear in community member role queries.

​
Best Practices

Performance Optimization: Use appropriate filters to reduce data transfer. Only query banned members when necessary, and cache frequently accessed member lists.

​
Query Optimization

  1. Filter Early: Use specific filters to reduce result sets
  2. Role Filtering: Query specific roles only when needed
  3. Pagination: Implement proper pagination for large communities
  4. Search Debouncing: Debounce search queries to reduce API calls

​
User Experience Guidelines

  1. Loading States: Show skeleton screens during member data fetching
  2. Search Feedback: Provide clear search result counts and states
  3. Permission Awareness: Hide banned member queries from non-admin users

Community Membership

Manage joining and leaving communities

Community Moderation

Advanced member moderation and ban management

User Management

Core user identity and profile management

Roles & Permissions

Understanding role-based access control