Managing 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.

Initial Assumptions

The initial assumptions for all the code examples below are as follows:

    #include <privmx/endpoint/core/Connection.hpp>
    #include <privmx/endpoint/thread/ThreadApi.hpp>
    #include <privmx/endpoint/core/Buffer.hpp>
    // ...

	/* 
	All the values below like BRIDGE_URL, SOLUTION_ID, CONTEXT_ID 
	should be replaced by the ones corresponding to your Bridge Server instance.
	
	The private keys here are for demonstration purposes only. 
	Normally, they should be kept separately by each user and stored in a safe place,
	or generated from a password (see the derivePrivateKey() method in the Crypto API)
	*/

	std::string BRIDGE_URL {"http://localhost:9111"};
	std::string SOLUTION_ID {"YOUR_SOLUTION_ID"};
	std::string CONTEXT_ID {"YOUR_CONTEXT_ID"};

	std::string USER1_ID {"user_1"};
	std::string USER1_PUBLIC_KEY {"PUBLIC_KEY_1"};
	std::string USER1_PRIV {"PRIVATE_KEY_1"};

	std::string USER2_ID {"user_2"};
	std::string USER2_PUBLIC_KEY {"PUBLIC_KEY_2"};

	std::string USER3_ID {"user_3"};
	std::string USER3_PUBLIC_KEY {"PUBLIC_KEY_3"};

    // initialize Endpoint connection and Threads API
	auto connection {core::Connection::connect(USER1_PRIV, SOLUTION_ID, BRIDGE_URL)};
	auto threadsApi {thread::ThreadApi::create(connection)};

Creating Threads

To create a Thread, you need a name and a list of public key - userID pairs. See how to get them here. 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 Bridge API.

After creating a Thread, all the users with management rights will be able to edit the Thread. Skip to Modifying Threads for more info.

Below you can see some examples of creating Threads that function as a chat feature in your application, with access management capabilities similar to those found in other popular collaboration tools.

    // initialize Endpoint connection and Threads API
	auto connection {core::Connection::connect(USER1_PRIV, SOLUTION_ID, BRIDGE_URL)};
	auto threadsApi {thread::ThreadApi::create(connection)};

	std::vector<core::UserWithPubKey> managers {};
	managers.push_back({.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY});

	std::vector<core::UserWithPubKey> users {};
    users.push_back({.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY});
	users.push_back({.userId = USER2_ID, .pubKey = USER2_PUBLIC_KEY});

	// create a new Thread with access for user_1 as manager and user_2 as regular user
	auto threadId {threadsApi.createThread(CONTEXT_ID, users, managers, 
        core::Buffer::from("some thread's public meta-data"), 
        core::Buffer::from("some thread's private meta-data")
    )};

For C++ reference to here.

The user list in Threads is designed to be flexible, accommodating a wide range of use cases. Adding only two users creates a secure, encrypted one-on-one channel. Granting all users management rights results in a chat where everyone can edit the Threads.

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, last message 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.

Here's an example of how to download the last 30 Threads created within a Context:

    core::PagingQuery query = {.skip = 0, .limit = 30, .sortOrder = "desc"};

	// list threads
	auto result {threadsApi.listThreads(CONTEXT_ID, query)};
    for (auto thread: result.readItems) {
        std::cout << "Thread ID: " << thread.threadId << std::endl;
    }

To limit collecting too much data when downloading Threads, specify the page index (starting from 0) and the number of items to be included on each page.

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 Threads, delete them as a whole or particular messages.

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.

Below there is an example of modifying a Thread:

	std::vector<core::UserWithPubKey> managers {};
	managers.push_back({.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY});

    // Let's add a new user to the existing ones in the Thread
	std::vector<core::UserWithPubKey> newUsersList {};
    newUsersList.push_back({.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY});
	newUsersList.push_back({.userId = USER2_ID, .pubKey = USER2_PUBLIC_KEY});
	newUsersList.push_back({.userId = USER3_ID, .pubKey = USER3_PUBLIC_KEY});

    auto threadInfo {threadsApi.getThread(threadId)};

    threadsApi.updateThread(threadId, newUsersList, managers, 
        core::Buffer::from("some new thread's public meta-data"), 
        core::Buffer::from("some new thread's private meta-data"), threadInfo.version, false, false
    );

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 you want to prevent them from accessing the Thread.
• policies - allow you to manage access to Threads and messages. Read more about Policies.