Messaging

Perform 3Box messaging operations

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

Stateful

Create/Subscribe Thread

Read Messages

Add/Remove Messages

Capabilities

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

Param

Type

Description

space

String

The name of the space the thread is in

name

String

The name of the thread

firstModerator

String

The DID (or ethereum address) of the first moderator

members

Boolean

True if only members are allowed to post

opts

Object

Optional parameters

opts.profileServer

String

URL of Profile API server

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

Param

Type

Description

address

String

The OrbitDB address of the thread

opts

Object

Optional parameters

opts.profileServer

String

URL of Profile API server

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

To perform these operations, you must authenticate the space. This is because threads are stored inside of spaces.

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

Param

Type

Description

name

String

The name of the thread

opts

Object

Optional parameters

opts.firstModerator

String

DID of first moderator of a thread, by default, user is first moderator (ethereum address or 3id)

opts.members

Boolean

join a members only thread, which only members can post in, defaults to open thread

opts.noAutoSub

Boolean

Disable auto subscription to the thread when posting to it (default false)

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

Param

Type

Description

address

String

The full address of the thread

opts

Object

Optional parameters

opts.noAutoSub

Boolean

Disable auto subscription to the thread when posting to it (default false)

space.subscribeThread(address, config)

Subscribe to the given thread, if not already subscribed

Kind: instance method of Space

Param

Type

Description

address

String

The address of the thread

config

Object

configuration and thread meta data

opts.name

String

Name of thread

opts.firstModerator

String

DID of the first moderator (ethereum address or 3id)

opts.members

String

Boolean string, true if a members only thread

space.unsubscribeThread(address)

Unsubscribe from the given thread, if subscribed

Kind: instance method of Space

Param

Type

Description

address

String

The address of the thread

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

Param

Type

Description

message

Object

The message

Example:

await thread.post('hello world!')

thread.deletePost(id)

Delete post in a thread.

Kind: instance method of Thread

Param

Type

Description

id

String

Post Id

Example:

await thread.deletePost(postID)

Who can remove posts?

Users are always permitted to remove their own posts. Moderators are also able to remove the posts of anyone in the thread, including other moderators.

thread.addModerator(id)

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

Kind: instance method of Thread

Param

Type

Description

id

String

Moderator Id (ethereum address or 3id)

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

Param

Type

Description

id

String

Member Id (ethereum address or 3id)

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

Param

Type

Description

updateFn

function

The function that will get called