Metadata

In Comments, each thread and comment can be given custom metadata. This is helpful for integrating Comments into various applications, for example it can be used to store:

• The priority, status, or category of a thread.
• Coordinates or timestamps related to the thread.
• Quoted text in a text editor.
• Tags, context, or flags on a comment.
• External IDs like Slack message IDs on comments to build two-way integrations.

Valid metadata

You can store any string, boolean, or number in metadata, for example:

metadata: {  priority: "URGENT",  pinned: false,  timestamp: 1703073188013,}

Setting a property to null will remove it.

metadata: {  timestamp: null,}

You can store up to 50 metadata properties per thread or comment, and each property can be 4000 characters long.

Setting metadata

Metadata can be set using the default components, React hooks, or by editing threads and comments using the REST APIs. But before making any changes, it’s recommended to set your metadata types in your config file.

declare global {  interface Liveblocks {    ThreadMetadata: {      priority: string;      pinned: boolean;      timestamp: number;    };    CommentMetadata: {      slackMessageTs: string;      spam: boolean;      upvotes: number;    };
    // ...  }}

Learn more about typing your data.

Composer component

The <Composer /> component is used to create threads and comments, and by default it’ll create a new thread, with optional metadata, when its form is submitted.

When using it to create a thread, you can pass custom metadata, which will be attached to the thread.

import { Composer } from "@liveblocks/react-ui";
// Creates a new thread with custom metadatafunction Component() {  return (    <Composer      metadata={{        // Custom metadata here        priority: "URGENT",        pinned: false,        timestamp: 1703073188013,      }}    />  );}

When using it to reply to a thread, you can also pass custom metadata, which will be attached to the comment.

import { Composer } from "@liveblocks/react-ui";
// Creates a new reply to an existing thread with custom metadatafunction Component({ threadId }) {  return (    <Composer      threadId={threadId}      commentMetadata={{        // Custom metadata here        tag: "engineering",        reviewed: false,      }}    />  );}

Mutation hooks

Several mutation hooks allow you to edit thread and comment metadata: useEditThreadMetadata, useEditCommentMetadata, and useCreateThread. Here’s one way to create a button that sets the pinned metadata property to true on a thread.

import { useEditThreadMetadata } from "@liveblocks/react/suspense";
// Button that sets `pinned` metadata to `true`function Component() {  const editThreadMetadata = useEditThreadMetadata();
  return (    <button      onClick={() =>        editThreadMetadata({          threadId: "th_d75sF3...",          metadata: { pinned: true },        })      }    >      Pin thread    </button>  );}

Here’s an example of editing comment metadata:

import { useEditCommentMetadata } from "@liveblocks/react/suspense";
// Button that sets `spam` metadata to `true` on a commentfunction Component() {  const editCommentMetadata = useEditCommentMetadata();
  return (    <button      onClick={() =>        editCommentMetadata({          threadId: "th_d75sF3...",          commentId: "cm_agH76a...",          metadata: { spam: true },        })      }    >      Mark as spam    </button>  );}

REST APIs

It’s possible to modify metadata from our REST APIs using the @liveblocks/node package. Here’s an example using liveblocks.editThreadMetadata for threads.

import { Liveblocks } from "@liveblocks/node";
// Create a Node.js clientconst liveblocks = new Liveblocks({ secret: "sk_prod_xxxxxxxxxx…xxxxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx" });
// Edit a thread's `priority` metadata, passing the user ID that made the changeawait liveblocks.editThreadMetadata({  roomId: "my-room-id",  threadId: "th_d75sF3...",
  data: {    metadata: {      priority: "IMPORTANT",    },    userId: "florent@example.com",  },});

And here’s an example using liveblocks.editCommentMetadata for comments.

import { Liveblocks } from "@liveblocks/node";
// Create a Node.js clientconst liveblocks = new Liveblocks({ secret: "sk_prod_xxxxxxxxxx…xxxxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx" });
// Edit a comment's `tag` metadata, passing the user ID that made the changeawait liveblocks.editCommentMetadata({  roomId: "my-room-id",  threadId: "th_d75sF3...",  commentId: "cm_agH76a...",
  data: {    metadata: {      tag: "engineering",    },    userId: "florent@example.com",  },});

The same result can also be achieved directly through our edit thread metadata REST API.

$curl -X POST https://api.liveblocks.io/v2/rooms/my-room-id/threads/th_d75sF3.../metadata \  -H "Authorization: Bearer YOUR_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{"metadata": {"priority": "IMPORTANT"}, "userId": "florent@example.com"}'

And our edit comment metadata REST API.

$curl -X POST https://api.liveblocks.io/v2/rooms/my-room-id/threads/th_d75sF3.../comments/cm_agH76a.../metadata \  -H "Authorization: Bearer YOUR_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{"metadata": {"tag": "engineering"}, "userId": "olivier@example.com"}'