​ Messaging (Threads) API methods allow developers to perform various actions on messaging threads including: creating threads, getting and setting data to threads, and adding moderators.

Threads are feed stores 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.

Static

View Thread

• ​Box.getThread​

• ​Box.getThreadByAddress​

Stateful

Create/Subscribe Thread

• ​space.joinThread​

• ​space.joinThreadByAddress​

• ​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.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()
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

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​