Messages

Threads allow the exchange of messages. In this section, let's take a closer look at the structure of messages and how to send them. We will also discuss some good practice when working with Threads.

About Messages

The structure of a message and a brief description of its elements is outlined in the following table:

Define structure

Thread's architecture does not require you to use a specific data structure inside the messages. So before working with Threads, define what what kind of messages you want to send.

We recommend future-proofing your messages right from the start, i.e. choosing an easily modifiable format.

It is also a good idea to include its type and version in the structure of the message.

Here is an example message structure that you can use in your project.

{
    “data”:{
        “content”: "string", // string / binary data containing for example: markdown, html or json
    },
        “info”: "ServerInfo", // assigned by server,
        “publicMeta”:{
        “version”:number,
        “type”: “text”, // some kind of enum describing type of message like “event”, “html”,“markdown” etc.
    },
        “privateMeta”:{
        // meta fields
    }
}

Remember that it is only an example and you should consider your app's requirements and limitations.

Sending

With the structure ready, its time to start sending messages.

auto msgId {threadApi.sendMessage(
    THREAD_ID,
    core::Buffer::from("some message public meta-data"), 
    core::Buffer::from("some message private meta-data")
    core::Buffer::from("message data")
)};

After sending the message, you will get its ID returned.

Message IDs are unique within a Context, allowing you to locate a message solely by its ID, without the need to know the associated Thread ID.

Using Message Metadata

Metadata fields inside messages make it easier to integrate Threads into new and existing projects. Threads are scheme agnostic by design, which makes them easy to integrate into any application. Metadata also allows developers to add any functionalities required by their app.

PrivateMeta

privateMeta includes additional sensitive information about the message. It's useful when we need to include the user's private data (personal information, activity details) in the message.

Like the content of the message itself, privateMeta is encrypted before sending. Since it is saved as binary data, you are free to choose any format. It can be a JSON parsed to a binary array or a more efficient binary format such as Protocol Buffers.

PublicMeta

Unlike privateMeta, publicMeta is not encrypted. It's useful when you want to include some additional info that does not require encryption.

publicMeta also does not have a specified structure and supports any binary format.

Example: Response To Another Message

Let's say that you need to implement replies to other messages inside a Thread using publicMeta.

When sending a message, include the ID of the message you want to reply to. Expanding on the example from the section on sending, it would look like that:

{
    "data":{
        "content": "string" // string / binary data containing for example: markdown, html or json
    },
    "info": "ServerInfo", // assigned by server,
    "publicMeta":{
        "version":"number",
        "type": “text”, // some kind of enum describing type of message like “event”, “html”,“markdown” etc.
        "responseTo":”{messageID}”
    },
}

When displaying the message in a chat, you will be able to find the message that was mentioned and display it according to the application's requirements.

Listing Messages

Your application may include multiple messages, each associated with different Threads. You can retrieve a list of all messages within a given Thread.

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

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

auto result {threadApi.listMessages(THREAD_ID, query)};
for (const auto& message : result.readItems) {
    std::cout << "Message ID: " << message.info.messageId << std::endl;
}

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

Modifying Messages

Depending on your project's specification, it may be necessary to modify a message. It could be e.g. changing message data, publicMeta, privateMeta. Each user with management rights is able to modify message.

Updating a message means overwriting it with the provided data. To successfully update a message, you must be the message creator or a Thread moderator.

Below there is an example of modifying a message:

threadApi.updateMessage(
    msgId,  
    core::Buffer::from("some new message public meta-data"), 
    core::Buffer::from("some new message private meta-data"), 
    core::Buffer::from("message data")
);

Deleting Message

To successfully delete a message, you must be the message creator or a Thread moderator.

Below there is an example of deleting a Thread:

threadApi.deleteThread(threadId);