Query Channel Members

Search and retrieve channel members with advanced filtering by membership status, roles, and sorting options

Query channel members filtered by membership status (active, muted, banned), role, or deletion status. Results are paginated and returned as a Live Collection.

Query Capabilities

Member querying supports filtering by status, role, and deletion state, with configurable sorting. Results paginate automatically via Live Collections.

Advanced Filtering

Multiple filter criteria

• Membership status filtering (active, muted, banned)
• Role-based member filtering
• Include/exclude deleted users
• Configurable sorting options

Paginated Results

Efficient data loading

• Pagination support for large member lists
• Real-time updates with Live Collections
• Search functionality with keyword matching
• Customizable page sizes and limits

Implementation Guide

Basic Query

Essential member retrieval functionality

Query members within a chat channel with flexible filtering and sorting options. This enables comprehensive member discovery and management within your chat application.

Required Parameters

Parameter	Type	Description
channelId	String	Unique identifier of the channel to query members from

Optional Parameters

Parameter	Type	Default	Description
filter	FilterEnum	ALL	Filter members by membership status (ALL, MEMBER, MUTED, BANNED)
roles	Array<String>	[]	Filter members by specific roles assigned in the channel
includeDeleted	Boolean	false	Include members whose user accounts have been deleted
sortBy	SortEnum	LAST_CREATED	Sort order for member results (FIRST_CREATED, LAST_CREATED)

Code Examples

iOS

var token: AmityNotificationToken?

func queryMemberExample() {
  let membershipParticipation = AmityChannelMembership(channelId: "channel1")
    token = membershipParticipation
                .getMembers(filter: .all, sortBy: .firstCreated, roles: [])
                .observe { collection, error in
        // ...
    }
}

Member Count Calculation: Channel member count value is based on all members in the channel including the members whose user has been deleted.

Advanced Filtering

Role-based and status-specific queries

Implement sophisticated member filtering to find specific member categories or user roles within your channels.

Filter by Membership Status

iOS

// Query only active members
let activeMembers = membershipParticipation
    .getMembers(filter: .all, sortBy: .lastCreated, roles: [])
    .observe { collection, error in
        // Handle active members only
    }

// Query muted members for moderation
let mutedMembers = membershipParticipation
    .getMembers(filter: .mute, sortBy: .firstCreated, roles: [])
    .observe { collection, error in
        // Handle muted members
    }

Search Members

Keyword-based member discovery

Enable users to search for specific members by name or username within channels for enhanced user experience.

Search Implementation

iOS

// Search members by keyword
var token: AmityNotificationToken?

let builder = AmityChannelMembershipFilterBuilder()
builder.add(filter: .member)

token = channelMembership.searchMembers(
displayName: "<display-Name>", 
filterBuilder: builder, 
roles: [], 
includeDeleted: false
)
.observe({ collection, error in
//..
})

Search Performance: Implement debounced search input to optimize API calls and improve user experience during member discovery.

API Reference

Filter Options

Membership status filtering

• ALL: Members with any membership status
• MEMBER: Only active members
• MUTED: Only muted members
• BANNED: Only banned members

Sort Options

Result ordering

• FIRST_CREATED: Oldest members first
• LAST_CREATED: Newest members first

Membership Status Filters

Filter	Description	Use Case
ALL	Members with any membership status	General member lists, comprehensive views
MEMBER	Only active members	User-facing member lists, active participant views
MUTED	Only muted members	Moderation interfaces, review muted users
BANNED	Only banned members	Administrative tools, ban management

Role-Based Filtering

Parameter	Type	Description
roles	Array<String>	Filter members by specific roles (e.g., “moderator”, “admin”)

Data Inclusion Options

Parameter	Type	Description
includeDeleted	Boolean	Whether to include members whose user accounts have been deleted

Sorting Options

Sort Option	Description	Behavior
FIRST_CREATED	Sort by membership creation date ascending	Shows oldest members first
LAST_CREATED	Sort by membership creation date descending	Shows newest members first

Membership Creation Date: The membership creation date refers to when the user joined the channel, not when their user account was created.

Best Practices

Query Optimization

Performance and efficiency strategies

Targeted Filtering

• Use specific filters to reduce result set size and improve load times
• Combine multiple filter criteria when searching for specific member types
• Consider your use case when deciding whether to include deleted users

Pagination Management

• Implement proper pagination for channels with large member counts (>20 members)
• Use appropriate page sizes (20-50 items) to balance performance and UX
• Load additional pages only when needed to conserve bandwidth

Member Status Management

Handling different member states effectively

Status-Specific UI Design

• Active Members: Primary focus for user-facing features and interactions
• Muted Members: Separate moderation views with clear status indicators
• Banned Members: Administrative interfaces with appropriate warnings
• Deleted Users: Consider data retention and privacy requirements

Real-Time Status Updates

• Utilize live collections to receive instant status changes
• Update UI immediately when member status changes
• Handle status transitions gracefully in your interface

Privacy Considerations

• Respect user privacy when displaying member information
• Implement appropriate access controls for sensitive member data
• Consider anonymization for deleted user accounts

Search & Discovery UX

User experience optimization for member discovery

Search Implementation

• Implement debounced search (300-500ms delay) to reduce API calls
• Provide real-time search results as users type
• Show search suggestions or recent searches for better UX

Filter Interface Design

• Provide intuitive filter controls for membership status and roles
• Show active filter indicators and easy reset options

Loading States & Feedback

• Show appropriate loading indicators during queries
• Implement skeleton screens for better perceived performance
• Provide clear error messages when queries fail

Progressive Enhancement

• Load basic member list first, then apply filters
• Implement infinite scroll for seamless browsing
• Cache search results for faster subsequent queries

Role-Based Access

Implementing proper access controls

Permission-Based Queries

• Filter query results based on user permissions
• Restrict sensitive member information to authorized users only
• Implement role-based visibility controls

Administrative Features

• Provide comprehensive member management for admins and moderators
• Include banned and muted member views for moderation purposes
• Implement bulk actions for efficient member management

User Privacy

• Respect channel privacy settings when displaying members
• Implement appropriate member visibility controls
• Consider opt-out preferences for member discovery

Example: Permission-Based Filtering

fun getVisibleMembers(userRole: String): Flowable<PagingData<AmityChannelMember>> {
    val filter = when (userRole) {
        "admin", "moderator" -> AmityChannelMembershipFilter.ALL
        else -> AmityChannelMembershipFilter.MEMBER
    }
    
    return channelRepository.membership(channelId)
        .getMembers()
        .filter(filter)
        .build()
        .query()
}

Implementation Strategy: Start with basic member queries using default parameters, then progressively add filtering, search, and role-based access as your application grows. Use specific filters and pagination to optimize performance for channels with large member counts.