Add Persistent Threads

Support Persistent message threads in your app

Getting Started with Persistent Threads

Persistent threads (open, members, personal) are 3Box threads where messages are stored in and made available by a persistent OrbitDB feed store shared between users. Messages persist unless they are explicitly removed by the author or a moderator.

This page provides step by step instructions on how to add Persistent Threads to your application:

Want to quickly get started with Persistent Threads? Try 3Box Comments plugin!

We have created a 3Box comments plugin, which is the easiest way to add a persistent commenting section to your react application.

Explore the 3Box Comments Plugin

1. Configure your new Persistent Thread

Before getting started, you should consider a few configuration options for your Persistent Thread, which will make later steps more simple.

You only need to perform this step if you are creating a new Persistent Thread. If you want to join an existing thread, then proceed to the next step.

Decide on a Persistent Thread Type

The first step in configuring a Persistent Thread is making sure you actually need a Persistent Thread, and not a Ghost Thread.

After you're sure that Persistent Threads are best suited to your use case, you need to decide which type of Persistent Thread is most appropriate: Open, Members, or Personal.

If you're unsure which type of thread to implement, read the previous page on choosing your thread.

Choose a name for your Space

Persistent Threads are stored in OrbitDB feed stores, and references to these threads are stored publicly in your application's space. These spaces are created and exist inside the 3Box of each user that joins the thread, not in one single global space. Before proceeding you should choose a name for the space that you will use to store your app's thread references.

In most cases, the name of the space should be the name of your application.

We recommend simply using the name of your application for this threads space, unless you want your application's threads kept in a different space for some reason. This space is an OrbitDB key-value store, so you can also keep other information and data related to your application inside it.

For example, if your application is called CheeseWizards, we would recommend your space be named cheeseWizards.

Choose a naming convention for your Threads

All Persistent Threads are uniquely identified by their space name, thread name, firstModerator, and members option. If any of these variables differs, you will get an entirely different thread.

Space name was chosen in the previous step, firstModerator defaults to the DID of the user who first created the thread, and members is a true/false boolean that indicates if you decided to create a members thread type.

For thread name, we recommend creating some standard convention that allows your application to easily create and manage many threads. While you can decide what this convention is, you may consider using some URL, or a topic, or something else unique.

2. Create or join a Persistent Thread

To perform various interactions with a message thread, such as creating or joining a thread, posting messages, removing messages, adding moderators, and adding members, you must first authenticate the space wherein the thread is stored.

Now that you have decided on the configuration options for your Persistent Thread, the first step in actually adding them to your application is allowing users to create new threads or join existing ones.

To create a new thread or join an existing one, you will need use the space.joinThread() method, and know the variables that uniquely identify your thread (space name, thread name, firstModerator, and members option).

Scroll to the appropriate section based on the Persistent Thread type you are implementing.

Persistent, Open Threads

Use one of the two options below to create or join an open thread:

Create or join an Open Thread using manual options

const thread = await space.joinThread('myThread', {
firstModerator: <ethereum-address or 3id>,
members: false

Create or join an Open Thread using default options

const thread = await space.joinThread('myThread')

Default options will assign firstModerator to be the current user that is joining the thread and members will be set to false. In other words, you will create or join a Persistent, Open Thread where you are the firstModerator.

Persistent, Members Threads

Create or join a Members Thread

const thread = await space.joinThread('myThread', {
firstModerator: <ethereum-address or 3id>,
members: true

Add new members to the thread

Use this code to allow moderators to add members to this thread:

await thread.addMember(<ethereum-address or 3id>)

Persistent, Personal Threads

Create or join a Personal Thread

const thread = await space.joinThread('myThread', {
members: true

3. View posts in the Persistent Thread

Display Posts

To get all posts in a thread, use thread.getPosts().

const posts = await thread.getPosts()
// you can also specify a number of posts you want
const posts = await thread.getPosts(20)

Listen for new updates

To listen for updates to a thread, such as new posts, use thread.onUpdate(). This will allow you to immediately display new messages posted in the thread in your application.


4. Add posts to a Persistent Thread

To post in a thread, a user must first create or join the thread using the steps above. After they have joined a thread, they can add a message to the thread using the method.

Everyone who can read the thread will have access to the message.

await'hello world')

5. More Options and Configurations

For more information on adding moderators, adding members, removing posts, and more, read the full Messaging API documentation.