Pinning channels

The channel pinning feature provides the following capabilities:

• Pin a channel in the channel list using the isPinned property.
• Pin a channel within a specific channel tag group (requires the channel tag feature).
• All channel types support pinning.

Pin in the channel list

When you pin a channel, the SDK sets its isPinned field and syncs the state to the server. Nexconn automatically syncs pin status across the user's devices. The client can proactively retrieve the latest data or receive updates through a listener.

Pin a channel

Call channel.pin() to pin a channel.

Kotlin

kotlin

val channel = DirectChannel("userId")

channel.pin { success, error ->
    if (error == null && success == true) {
        // Pinned successfully
        println("Channel pinned: isPinned=${channel.isPinned}")
    } else {
        // Pin failed: ${error?.message}
    }
}

Java

Java

DirectChannel channel = new DirectChannel("userId");

channel.pin(new OperationHandler<Boolean>() {
    @Override
    public void onResult(Boolean success, NCError error) {
        if (error == null && success != null && success) {
            // Pinned successfully
        } else {
            // Pin failed
        }
    }
});

Unpin a channel

Call channel.unpin() to unpin a channel.

Kotlin

kotlin

val channel = DirectChannel("userId")

channel.unpin { success, error ->
    if (error == null && success == true) {
        // Unpinned successfully
    } else {
        // Unpin failed: ${error?.message}
    }
}

Java

Java

DirectChannel channel = new DirectChannel("userId");

channel.unpin(new OperationHandler<Boolean>() {
    @Override
    public void onResult(Boolean success, NCError error) {
        if (error == null && success != null && success) {
            // Unpinned successfully
        } else {
            // Unpin failed
        }
    }
});

Check pin status

Check the pin status using the isPinned property on the channel object. Call reload() to refresh the latest state from the local database before reading the property.

Kotlin

kotlin

val channel = DirectChannel("userId")

channel.reload { updatedChannel, error ->
    if (error == null && updatedChannel != null) {
        if (updatedChannel.isPinned) {
            println("Channel is pinned")
        } else {
            println("Channel is not pinned")
        }
    }
}

Java

Java

DirectChannel channel = new DirectChannel("userId");

channel.reload((updatedChannel, error) -> {
    if (error == null && updatedChannel != null) {
        if (updatedChannel.getIsPinned()) {
            System.out.println("Channel is pinned");
        } else {
            System.out.println("Channel is not pinned");
        }
    }
});

Listen for pin status changes

Use ChannelHandler to listen for channel status changes, including pin status.

Kotlin

kotlin

NCEngine.addChannelHandler("STATUS_HANDLER", object : ChannelHandler {
    override fun onChannelPinnedSync(event: ChannelPinnedSyncEvent) {
        println("Channel ${event.channelIdentifier.channelId} pin status: ${event.isPinned}")
    }
})

Java

Java

NCEngine.addChannelHandler("STATUS_HANDLER", new ChannelHandler() {
    @Override
    public void onChannelPinnedSync(@NonNull ChannelPinnedSyncEvent event) {
        System.out.println("Channel " + event.getChannelIdentifier().getChannelId() + " pin status: " + event.getIsPinned());
    }
});

Pin within a tag

If you use the channel tag feature, you can pin channels within a specific tag group. See Tagging Channels for details.

Notes

1. The client auto-generates channels and channel lists from local message data. Pin status is synced across all devices where the user is logged in.
2. If the channel does not yet exist when you call the pin API, the SDK automatically creates it and pins it.
3. Pin status syncs automatically across multiple devices.
4. Use ChannelHandler to receive real-time pin status updates.