Skip to main content

Retrieve channels

The Chat SDK generates and maintains a local channel list in the database based on sent and received messages. You can retrieve channels from this local store. Community channels can also be included in the list if the feature is enabled for your app. Submit a ticket to enable it.

Get one or more channels​

Call BaseChannel.getChannels(identifiers:completion:) to retrieve channel details by identifier.

swift
import NexconnChatSDK

let id1 = ChannelIdentifier(channelType: .direct, channelId: "userId")
let id2 = ChannelIdentifier(channelType: .group, channelId: "groupId")

BaseChannel.getChannels(identifiers: [id1, id2]) { channels, error in
    guard let channels, error == nil else {
        print("Error fetching channels: \(error?.localizedDescription ?? "unknown error")")
        return
    }

    print("Fetched channels: \(channels.count)")
}
ParameterTypeDescription
identifiersNSArray<NCChannelIdentifier *>Channel identifiers to query
completionBlockResult callback; returns the channel array on success, or NCError on failure

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 BaseChannel.syncRemoteChannels(completion:) to sync up to 1,000 channels from the server to the local database.

This method only triggers the sync request. Listen for onRemoteChannelsSyncCompleted(_:) on ChannelHandler to know when the sync finishes.

swift
import NexconnChatSDK

BaseChannel.syncRemoteChannels { error in
    if error == nil {
        print("Sync request sent")
    }
}
swift
import NexconnChatSDK

final class ChannelSyncService: NSObject, ChannelHandler {
    func start() {
        NCEngine.addChannelHandler(identifier: "MyHandler", handler: self)
    }

    func onRemoteChannelsSyncCompleted(_ event: RemoteChannelsSyncCompletedEvent) {
        if event.error == nil {
            print("Channel sync complete")
        } else {
            print("Channel sync failed: \(event.error!.localizedDescription)")
        }
    }
}

Get channel list (paginated)​

Use BaseChannel.createChannelsQuery(params:) to retrieve the local channel list page by page. Results are sorted by time in descending order, and pinned channels are prioritized by default.

Pass 0 as the initial startTime. For later pages, the SDK advances the cursor internally after each loadNextPage(_:) call.

swift
import NexconnChatSDK

let params = ChannelsQueryParams()
params.setChannelTypes([.direct, .group])
params.pageSize = 100
params.startTime = 0
params.topPriority = true

let query = BaseChannel.createChannelsQuery(params: params)
query.loadNextPage { page, error in
    guard let channels = page?.data, error == nil else {
        print("Failed to load channels: \(error?.localizedDescription ?? "unknown error")")
        return
    }

    print("Loaded channels: \(channels.count)")
}
ParameterTypeDescription
channelTypesNSArrayArray of channel types. Required.
pageSizeint32Number of channels to retrieve per page. Default is 20.
startTimelong longTimestamp cursor. Pass 0 for the first page.
topPriorityBOOLWhether to prioritize pinned channels. Default is YES.

Get unread channel list​

Call BaseChannel.getUnreadChannels(_:completion:) to get channels with unread messages. This API supports direct, group, and system channels.

swift
import NexconnChatSDK

BaseChannel.getUnreadChannels(
    channelTypes: [
        NSNumber(value: ChannelType.group.rawValue),
        NSNumber(value: ChannelType.system.rawValue),
        NSNumber(value: ChannelType.direct.rawValue),
    ]
) { channels, error in
    guard let channels, error == nil else {
        return
    }

    print("Unread channels: \(channels.count)")
}

Get channels with unread mentions​

Use BaseChannel.createUnreadMentionMeChannelsQuery(params:) to get channels where the current user has unread mentions. This API 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
    guard let channels = page?.data, error == nil else {
        return
    }

    print("Unread mention channels: \(channels.count)")
}
ParameterTypeDescription
channelTypesNSArrayChannel type array. Required.
topPriorityBOOLWhether to prioritize pinned channels. Default is YES.
startTimelong longStart time for the query. Pass 0 for the latest page.
pageSizeNSUIntegerNumber of results per page. Default is 20.

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.
  • A new device may not yet have local message history.
  • If multi-device message sync is enabled, the server syncs only recent messages, which can 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. Submit a ticket if you need this.
  • Maintain the channel list on your app server and use server-side history APIs when you need a complete historical list.
Last updated on