Add Ghost Threads

Support Ghost message threads in your app

Getting Started with Ghost Threads

Ghost threads are a different type of thread that doesn't persist any messages to database storage. Instead, messages are sent from one peer to the rest of the network using ipfs pubsub, and upon receipt by other online peers are kept in-memory. New users coming online or just joining the network can request the message history from online peers.

Ghost Threads are currently only available in the open variety, meaning that any user who knows the Ghost Thread name can join and post messages in the thread.

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

1. Configure your new Ghost Thread

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

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

Confirm you need a Ghost Thread

The first step in configuring a Ghost Thread is making sure you actually need a Ghost Thread, and not a Persistent Thread. If you're unsure which type of thread to implement, read the previous page on choosing your thread.

Choose a name for your Space

Ghost Threads are access controlled using 3Box spaces. These spaces are created and exist inside the 3Box of each user that joins the Ghost 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 Ghost Threads.

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 managed by 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 namedcheeseWizards.

Choose a naming convention for your Threads

All Ghost Threads are uniquely identified by their space name and thread name. If either of these variables differs, you will get an entirely different thread.

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. Join a new or existing Ghost Thread

Authenticate the Space

The first step in interacting with Ghost Threads is to authenticate the Space where the thread(s) will be accessed and referenced. This should have already been done in Step 3. Authenticate a Space of the overall flow of adding 3Box to your web app, but if you haven't first authenticated the Space for your Ghost Threads, use this code to do so:

const space = await box.openSpace('mySpace')

Note: If the user already has a space with this name, your application will gain access to it; if the user does not have the space, this method will automatically create one for them.

Join a new or existing Ghost Thread

Whether you're creating a new Ghost Thread or joining an existing one, you will need the name of the Ghost Thread to begin reading and adding messages to it. In the code example below, let space be the space from the previous step, and 'myThread' be your specific thread name.

Use the space.joinThread() method to join a new or existing Ghost Thread:

const thread = await space.joinThread('myThread', {
ghost: true,
ghostBacklogLimit: 20 // optional and defaults to 50
})

3. View posts of a Ghost Thread

Display current posts in a Ghost Thread

To get all posts in a thread or request a specific number of messages from the backlog, use thread.getPosts().

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

Listen for updates to the Ghost Thread

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.

thread.onUpdate(() => {
const posts = await thread.getPosts()
console.log(posts)
})

4. View Members in a Ghost Thread

List current members in a Thread

The listMembers() method will return an array of space 3IDs for users in the chatroom.

const userList = await thread.listMembers()

Update when members join or leave the Thread

Use this code to optionally post a 'User joined/left the chat' message to the thread when new users join or leave:

thread.onNewCapabilities((event, did) => console.log(did, event, ' the chat'))

The event parameter is a string that is either: joined or left.

5. Add posts to a Ghost Thread

Broadcast message to all peers

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

await thread.post('hello everyone')

6. Leave a Ghost Thread

Leave the Ghost Thread

await thread.close()