​💬 Messaging (Threads) API methods allow developers to perform various operations on message threads including: creating threads, joining threads, making and viewing posts, adding moderators, and more.

Threads are feeds that are great for supporting social messaging, commenting, and chat systems between one or many users, for any application. They're also great for creating single or multi-user content streams and sharing data between users.

Threads are available as either persistent threads, where messages are available in a persistent OrbitDB feed store unless explicitly removed (by the author or a moderator), or ghost threads, where messages are not persisted in a database but whose history is kept in-memory by online peers and can be requested by new users. For ghost threads, if all peers go offline then messages disappear.

For simplicity, we tried to keep the APIs for Persistent and Ghost Threads as similar as possible. Follow these links to learn how to implement Persistent Threads and Ghost Threads.

Static

View Thread

• ​Box.getThread​

• ​Box.getThreadByAddress​

Stateful

Create/Subscribe Thread

• ​space.joinThread​

• ​space.joinThreadByAddress​

• ​space.createConfidentialThread​

• ​space.subscribeThread​

• ​space.unsubscribeThread​

• ​space.subscribedThreads​

Read Messages

• ​thread.getPosts​

• ​thread.onUpdate​

Add/Remove Messages

• ​thread.post​

• ​thread.deletePost​

Capabilities

• ​thread.addModerator​

• ​thread.listModerators​

• ​thread.addMember​

• ​thread.listMembers​

• ​thread.onNewCapabilities​

Static

Box.getThread(space, name, firstModerator, members, opts)

View all posts made in a thread.

Kind: static method of Box Returns: Array.<Object> - An array of posts

Example

const posts = await Box.getThread(spaceName, threadName, firstModerator, membersThread)
console.log(posts)

Output:

[{
  author: "did:3:bafy..."
  message: "asdf"
  postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"
  timestamp: 1564419440
}, {
  author: "did:3:baf..."
  message: "lalal"
  postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"
  timestamp: 1564419467
}]

Box.getThreadByAddress(address, opts)

Get all posts that are made to a thread.

Kind: static method of Box Returns: Array.<Object> - An array of posts

Example:

const posts = await Box.getThreadByAddress(threadAddress)
console.log(posts)

Output:

[{
  author: "did:3:bafy..."
  message: "asdf"
  postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"
  timestamp: 1564419440
}, {
  author: "did:3:baf..."
  message: "lalal"
  postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"
  timestamp: 1564419467
}]

Stateful

space.joinThread(name, opts)

Join a thread. Use this to start receiving updates from, and to post in threads

Kind: instance method of Space Returns: Thread - An instance of the thread class for the joined thread

Example:

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

space.joinThreadByAddress(address, opts)

Join a thread by full thread address. Use this to start receiving updates from, and to post in threads

Kind: instance method of Space Returns: Thread - An instance of the thread class for the joined thread

space.createConfidentialThread(name, opts)

Join a thread. Use this to start receiving updates from, and to post in threads

Kind: instance method of Space Returns: Thread - An instance of the thread class for the joined thread

Example:

const thread = await space.createConfidentialThread('name')

space.subscribeThread(address, config)

Subscribe to the given thread, if not already subscribed

Kind: instance method of Space​

space.unsubscribeThread(address)

Unsubscribe from the given thread, if subscribed

Kind: instance method of Space​

space.subscribedThreads()

Get a list of all the threads subscribed to in this space

Kind: instance method of Space Returns: Array.<Objects> - A list of thread objects as { address, firstModerator, members, name}

thread.getPosts()

Example:

const posts = await thread.getPosts()
​
// optional ghost thread feature, get last n posts
// in ghost threads last 50 posts are returned by default
const posts = await thread.getPosts({ limit: 20 })
​
console.log(posts)

Output:

[{
  author: "did:3:bafy..."
  message: "asdf"
  postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"
  timestamp: 1564419440
}, {
  author: "did:3:baf..."
  message: "lalal"
  postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"
  timestamp: 1564419467
}]

thread.onUpdate()

Listen for updates to the thread. This method allows apps to listen for new posts in the thread, and perform an action when this occurs, such as adding the new message to the app's UI.

thread.post(message)

Post a message to the thread

Kind: instance method of Thread Returns: String - The postId of the new post

Example:

await thread.post('hello world!')

thread.deletePost(id)

Delete post in a thread.

Kind: instance method of Thread​

Example:

await thread.deletePost(postID)

thread.addModerator(id)

Add a moderator to this thread, throws error is user can not add a moderator

Kind: instance method of Thread​

thread.listModerators()

List moderators

Kind: instance method of Thread Returns: Array.<String> - Array of moderator DIDs

thread.addMember(id)

Add a member to this thread, throws if user can not add member, throw is not member thread. Members can only be added if they have already opened the space the thread lives in.

Kind: instance method of Thread​

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

thread.listMembers()

List members

Kind: instance method of Thread Returns: Array.<String> - Array of member DIDs

const members = await thread.listMembers()

thread.onNewCapabilities(updateFn)

Register a function to be called for every new capability that is added to the thread access controller. This includes when a moderator or member is added. The function takes one parameter, which is the capabilities obj, or you can call listModerator / listMembers again instead.

Kind: instance method of Thread​