💬 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.
View all posts made in a thread.
Kind: static method of Box
Returns: Array.<Object>
- An array of posts
Param | Type | Description |
space |
| The name of the space the thread is in |
name |
| The name of the thread |
firstModerator |
| The DID (or ethereum address) of the first moderator |
members |
| True if only members are allowed to post |
opts |
| Optional parameters |
opts.profileServer |
| URL of Profile API server |
const posts = await Box.getThread(spaceName, threadName, firstModerator, membersThread)console.log(posts)
[{author: "did:3:bafy..."message: "asdf"postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"timestamp: 1564419440}, {author: "did:3:baf..."message: "lalal"postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"timestamp: 1564419467}]
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 |
| The OrbitDB address of the thread |
opts |
| Optional parameters |
opts.profileServer |
| URL of Profile API server |
const posts = await Box.getThreadByAddress(threadAddress)console.log(posts)
[{author: "did:3:bafy..."message: "asdf"postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"timestamp: 1564419440}, {author: "did:3:baf..."message: "lalal"postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"timestamp: 1564419467}]
To perform these operations, you must authenticate the space. This is because threads are stored inside of spaces.
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 |
| The name of the thread |
opts |
| Optional parameters |
opts.firstModerator |
| DID of first moderator of a thread, by default, user is first moderator (ethereum address or 3id) |
opts.members |
| join a members only thread, which only members can post in, defaults to open thread |
opts.noAutoSub |
| Disable auto subscription to the thread when posting to it (default false) |
opts.ghost |
| Enable ephemeral messaging via Ghost Thread (default false) |
opts.ghostBacklogLimit |
| The number of posts to maintain in the ghost backlog (default 50) |
const thread = await space.joinThread('name')
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 |
| The full address of the thread |
opts |
| Optional parameters |
opts.noAutoSub |
| Disable auto subscription to the thread when posting to it (default false) |
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 |
| The name of the thread |
const thread = await space.createConfidentialThread('name')
Subscribe to the given thread, if not already subscribed
Kind: instance method of Space
Param | Type | Description |
address |
| The address of the thread |
config |
| configuration and thread meta data |
opts.name |
| Name of thread |
opts.firstModerator |
| DID of the first moderator (ethereum address or 3id) |
opts.members |
| Boolean string, true if a members only thread |
Unsubscribe from the given thread, if subscribed
Kind: instance method of Space
Param | Type | Description |
address |
| The address of the thread |
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}
| |
const posts = await thread.getPosts()// optional ghost thread feature, get last n posts// in ghost threads last 50 posts are returned by defaultconst posts = await thread.getPosts({ limit: 20 })console.log(posts)
[{author: "did:3:bafy..."message: "asdf"postId: "zdpuAtHovxguZuqPHP5YQmnSyL5T1owJvdFtMQGYJRHKX177i"timestamp: 1564419440}, {author: "did:3:baf..."message: "lalal"postId: "zdpuAtHovxgufewPHP5YQmnSyL5T1owJvdFtM23802394absc"timestamp: 1564419467}]
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.
Post a message to the thread
Kind: instance method of Thread
Returns: String
- The postId of the new post
Param | Type | Description |
message |
| The message |
to |
| PeerID to send the message to (optional and only for ghost threads) |
await thread.post('hello world!')
Delete post in a thread.
Kind: instance method of Thread
Param | Type | Description |
id |
| Post Id |
await thread.deletePost(postID)
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.
Add a moderator to this thread, throws error is user can not add a moderator
Kind: instance method of Thread
Param | Type | Description |
id |
| Moderator Id (ethereum address or 3id) |
List moderators
Kind: instance method of Thread
Returns: Array.<String>
- Array of moderator DIDs
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
Param | Type | Description |
id |
| Member Id (ethereum address or 3id) |
await thread.addMember(<etherum-address or 3id>)
List members
Kind: instance method of Thread
Returns: Array.<String>
- Array of member DIDs
const members = await thread.listMembers()
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 |
| The function that will get called |