---
meta:
title: "Concepts"
parentTitle: "Comments"
description: "Learn about threads and comments"
---
A quick overview of the concepts used in Liveblocks Comments.
## Threads
In Liveblocks Comments, everything revolves around _threads_. In each
[multiplayer room](/docs/concepts#Rooms) you can create a
number of threads. Each individual thread contains a list of _comments_ written
by your users.
Threads can be retrieved by
[a React hook](/docs/products/comments/hooks#threads-hook) or
[on your server](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads).
Here’s an example of a thread object.
```ts
{
type: "thread",
id: "th_sf8s6sh...",
roomId: "my-room-id",
createdAt: Date ,
resolved: false,
visibility: "public",
comments: [
// A list of comments in the thread
// ...
],
metadata: {
// Your custom thread metadata
// ...
},
}
```
Threads can store [custom metadata](/docs/products/comments/metadata), which is
helpful for integrating them into your product.
## Comments
Each comment is created by a user, referenced by their
[user ID](/docs/products/comments/users-and-mentions), and is part of a thread.
The first comment in a thread is displayed at the top.
Here’s an example of a single comment inside a thread object.
```ts
{
type: "thread",
id: "th_sf8s6sh...",
roomId: "my-room-id",
createdAt: Date ,
resolved: false,
visibility: "public",
comments: [
// +++
{
type: "comment",
threadId: "th_sf8s6sh...",
id: "cm_agH76a...",
roomId: "my-room-id",
userId: "alicia@example.com",
createdAt: Date ,
editedAt: Date ,
body: {
// The comment's text in `CommentBody` format
// ...
},
metadata: {
// Your custom comment metadata
// ...
},
},
// +++
// Other comments in the thread
// ...
],
metadata: {
// Your custom thread metadata
// ...
},
}
```
A comment’s `body` is in a custom `CommentBody` format, though you most likely
won’t need to use this, as we render it in React for you. We also provide a
number of functions that allow you to easily
[convert a comment’s body into Markdown, HTML, or plain text](/docs/api-reference/liveblocks-node#stringify-comment-body),
which is especially helpful for creating email notifications.
If you’re creating comments from Markdown on your server, you can also convert
Markdown into comment bodies with
[`markdownToCommentBody`](/docs/api-reference/liveblocks-node#markdown-to-comment-body).
Similarly to threads, comments can also store
[custom metadata](/docs/products/comments/metadata), which is helpful for
integrating them into your product.
### Deleted comments
Deleting a comment doesn’t remove the comment object from the thread, instead
the `comment.body` property is removed, and a `comment.deletedAt` property is
added, which contains the deletion time. This allows you to handle the deleted
comment in whichever way you see fit, for example you may like to create a
“message deleted” placeholder for the comment. Alternatively, the comment can be
hidden completely.
A thread is only deleted after all its comments have been deleted.
### Private comments
Each thread has a `visibility` that is either `"public"` or `"private"`, and
threads are public by default. Public and private threads work in the same way,
but when authenticating users, you can select whether the user should have
access to public or private threads.
Using the visibility option allows you to
[add private commenting to your app](/docs/guides/how-to-add-private-commenting-to-your-app),
enabling different two different tiers of commenting permissions in one room.
This is particularly useful for creating internal or team-only discussions,
whilst still allowing public comments for other users.
For a summary of the APIs, read
[how to use public and private threads](/docs/guides/how-to-use-public-and-private-threads).
Private threads are only available on Team and Enterprise plans.
---
For an overview of all available documentation, see [/llms.txt](/llms.txt).