Working with Threads

At their core, Threads provide a secure way for assigned members to exchange encrypted messages.

Threads allow users to communicate using topic-specific communication channels.
Each Context can contain any number of Threads with a unique identifier (threadId) used to distinguish them.
Threads do not need to have unique names or assigned public keys.

Permissions

Threads differentiate two types of users - Managers and Regular Users. The table below shows the differences in their permissions:

Activity	User	Manager
Sending messages	yes	yes
Editing Thread	no	yes
Deleting messages	only their own	all messages

The values above are the default policy values defined by PrivMX. To read more about Policies and learn how to modify them, go to Policies.

Before working with Threads, follow our Getting Started Guide. It will show you how to set up your project to work with PrivMX Bridge.

Sample code on this page is based on the initial assumptions.\

To access Threads methods, get the field threadApi from the active endpointSession. Session should be initialized with [.thread] passed to PrivmxEndpoint. §

Swift

endpointSession?.threadApi? // instance of ThreadApi

Creating Threads

To create a Thread, you need a name and a list of public key - userID pairs. Due to the fact that each Thread is inside a Context, all the public keys have to be registered inside the given Context. You can do it using PrivMX Bridge API.

After creating a Thread, all the users with management rights will be able to edit the Thread.

Creating a basic, unnamed Thread, which can act as an encrypted data container.

Swift

let users = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let managers = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let publicMeta = Data()
let privateMeta = Data()

_ = try? endpointSession?.threadApi?.createThread(
    in: contextId,
    for: users,
    managedBy: managers,
    withPublicMeta: publicMeta,
    withPrivateMeta: privateMeta,
    withPolicies: nil
    )

Listing Threads

Your application may include multiple Threads, each associated with different Contexts. You can retrieve a list of all Threads within a given Context. This list will include useful metadata about the Threads, such as the creation date, the last message upload date, user list, and information about the last modification. However, to optimize performance, the list will only include the total number of messages in each Thread, not the full message content.

Listing the most recent Threads in given Context:

Swift

var startIndex:Int64 = 0
var pageSize:Int64 = 100

guard let pagingList = try? endpointSession?.threadApi?
.listThreads(
    from:contextId,
    basedOn: .init(skip: startIndex, limit: pageSize, sortOrder: .desc)) else {return}

let threads = pagingList.readItems.map { $0 }

Modifying Threads

Depending on your project's specification, it may be necessary to modify a Thread. It could be e.g. changing the name or adding/removing users. Each user with management rights is able to modify Thread, delete them as a whole or only particular messages.

Three additional options are available when changing the list of users inside a Thread:

force - applies an update, without checking the current version;
forceGenerateNewKey - re-encrypts messages in the Thread. It's useful when a user is removed and we want to prevent them from accessing the Thread.
policies - allow you to manage access to Threads and messages. Read more about Policies.

Updating a Thread means overwriting it with the provided data. To successfully update a Thread, you must specify its current version. The version field is mandatory to handle multiple updates on the server and it is incremented by 1 with each update.

To update a Thread you must always provide its current version, as well as:

list of users
list of managers
new private and public meta (even if it didn't change)
Thread's current version
true if update action should be forced

Swift

struct ThreadPublicMeta:Codable{
    let tags: [String]
}
var threadID = "THREAD_ID"

        
let threadPublicMeta = ThreadPublicMeta(tags: ["TAG1","TAG2","TAG3"])
guard let publicMeta = try? JSONEncoder().encode(threadPublicMeta) else {return}
guard let thread = try? endpointSession?.threadApi?
    .getThread(threadID) else {return}

//users list to be extracted from thread
let users = thread.users.map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}
//managers list to be extracted from thread
let managers = thread.managers.map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}

guard let newPrivateMeta = "New thread name".data(using: .utf8) else {return}

_ = try? endpointSession?.threadApi?.updateThread(
    threadID,
    atVersion: thread.version,
    replacingUsers: users,
    replacingManagers: managers,
    replacingPublicMeta: thread.publicMeta.getData() ?? Data(),
    replacingPrivateMeta: newPrivateMeta,
    force:false,
    forceGenerateNewKey: false,
    replacingPolicies: nil)

Working with Threads

Permissions