Skip to main content

Retrieve channels

The Chat SDK generates and maintains a channel list in the local database based on sent and received messages. You can retrieve the channel list from the local database. The SDK supports including community channels in the list — submit a ticket to enable this feature.

Get a single channel​

Call reloadWithCompletion: on a channel instance to fetch the latest state from the server:

swift
import NexconnChatSDK
guard let channel = DirectChannel(channelId: "targetId") else { return }
channel.reload { updated, error in
    // Handle the channel
}
ParameterTypeDescription
channelIdNSStringThe other user's ID for direct channels
completionBlockResult callback returning an updated NCBaseChannel object

Get multiple channels​

Call [NCBaseChannel getChannels:completion:] to retrieve multiple channels at once.

tip

Supported channel types: direct, group, and system.

If only some channels exist locally, the completion returns only the available channels.

swift
import NexconnChatSDK
let id1 = ChannelIdentifier(channelType: .direct, channelId: "tId1")
let id2 = ChannelIdentifier(channelType: .direct, channelId: "tId2")
BaseChannel.getChannels(identifiers: [id1, id2]) { channels, error in
    if error == nil {
        // Handle channels
    } else {
        print("Error fetching channels: \(error?.localizedDescription ?? "unknown error")")
    }
}
ParameterTypeDescription
identifiersNSArrayChannel identifiers to query (max 100 per request)
completionBlockCallback with channel array and error

Sync remote channels to local​

tip

Submit a ticket to enable this feature.

When a user reinstalls the app or logs in on a new device, call [NCBaseChannel syncRemoteChannelsWithCompletion:] to sync up to 1,000 channels from the server to the local database.

This method only triggers the sync operation. Listen for the onRemoteChannelsSyncCompleted: callback from NCChannelHandler to know when syncing completes.

swift
import NexconnChatSDK
BaseChannel.syncRemoteChannels { error in
    // Sync request result
}
swift
import NexconnChatSDK
final class MyChannelHandler: NSObject, ChannelHandler {
    func onRemoteChannelsSyncCompleted(_ event: RemoteChannelsSyncCompletedEvent) {
        if event.error == nil {
            print("Channel sync complete")
        } else {
            print("Channel sync failed: \(event.error?.localizedDescription ?? "unknown error")")
        }
    }
}

let handler = MyChannelHandler()
NCEngine.addChannelHandler(identifier: "MyHandler", handler: handler)

Get channel list (paginated)​

Use NCChannelsQuery to retrieve the locally generated channel list page by page. Results are sorted by time in descending order, with pinned channels at the top by default.

Pass 0 as the initial startTime. For subsequent pages, use the operationTime property from the last channel in the previous page.

swift
import NexconnChatSDK
let params = ChannelsQueryParams()
params.setChannelTypes([.direct])
params.pageSize = 100
params.startTime = 0
let query = BaseChannel.createChannelsQuery(params: params)
query.loadNextPage { page, error in
    // Handle channels: page?.data
}

To disable pinned-first ordering, set topPriority to NO:

swift
import NexconnChatSDK
let params = ChannelsQueryParams()
params.setChannelTypes([.direct])
params.pageSize = 100
params.startTime = 0
params.topPriority = false
let query = BaseChannel.createChannelsQuery(params: params)
query.loadNextPage { page, error in
    // Handle channels: page?.data
}
ParameterTypeDescription
channelTypesNSArrayArray of channel types (wrap NCChannelType in NSNumber)
pageSizeintNumber of channels per page
startTimelong longTimestamp cursor. Pass 0 for the first page.
topPriorityBOOLWhether to prioritize pinned channels. Default YES.

Get unread channel list​

Call [NCBaseChannel getUnreadChannels:completion:] to get channels with unread messages. Supports direct, group, and system channels:

swift
import NexconnChatSDK
let channelTypes: [NSNumber] = [
    NSNumber(value: ChannelType.group.rawValue),
    NSNumber(value: ChannelType.system.rawValue),
    NSNumber(value: ChannelType.direct.rawValue)
]
BaseChannel.getUnreadChannels(channelTypes: channelTypes) { channels, error in
    // Handle channels with unread messages
}

Get channels with unread mentions​

Use NCUnreadMentionMeChannelsQuery to get channels where the current user has been mentioned but hasn't read the mention. Supports direct, group, system, and community channels.

swift
import NexconnChatSDK
let params = UnreadMentionMeChannelsQueryParams()
params.setChannelTypes([.direct, .group, .community])
params.pageSize = 100
params.startTime = 0
let query = BaseChannel.createUnreadMentionMeChannelsQuery(params: params)
query.loadNextPage { page, error in
    // Handle channels with unread mentions: page?.data
}
ParameterTypeDescription
channelTypesNSArrayChannel type array
topPriorityBOOLWhether to prioritize pinned channels. Defaults to YES.
startTimelong longStart time for the query. Pass 0 for the latest.
pageSizeNSUIntegerNumber of results. Valid range: 1–100.

Handling reinstalls or device switches​

If a user reinstalls the app or logs in on a new device, the channel list may appear empty or incomplete because:

  • Uninstalling deletes the local database, so there are no local messages to generate channels from.
  • On a new device, there may be no local message history.
  • If multi-device message sync is enabled, the server syncs messages from after midnight of the current day. This may result in a partial channel list.

To recover the previous channel list:

  • Request an extension of the missed message compensation period (up to 7 days). Note: A longer period may cause performance issues for users with high message volumes. Submit a ticket to request this.
  • Maintain the channel list on your app server and use the API to retrieve historical messages as needed.
Last updated on