Tiptap Docs

Server comments

Give your AI agents the ability to read, write and edit comments in your document, fully server-side.

See the source code on GitHub.

Experimental feature

This feature is experimental and the API will change in future releases.

Continuation from the AI agent chatbot guide

This guide continues the AI agent chatbot guide. Read it first.

Enable comment tools

To enable comment tools, pass the getThreads and editThreads options when fetching tool definitions from the Server AI Toolkit API.

const response = await fetch(`${apiBaseUrl}/toolkit/tools`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  body: JSON.stringify({
    schemaAwarenessData,
    tools: {
      // Disable tiptap edit tool so that the AI can not edit the document,
      // only add comments
      tiptapEdit: false,
      // Enable comment tools
      getThreads: true,
      editThreads: true,
    },
  }),
})

Execute comment tools

Comment tools require a Tiptap Cloud document because threads and comments are stored on the Tiptap Document Server. You do not need to pass the document field when using experimental_documentOptions — the AI Server fetches it from the Document Server automatically.

JWT requirements

Your JWT must include Document Server credentials as claims:

  • experimental_document_server_id (string): The Tiptap Cloud Document Server ID
  • experimental_document_server_management_api_secret (string): The management API secret for the Document Server

Request body

Include experimental_documentOptions in the request body:

  • documentId (string, required): The ID of the document
  • userId (string, optional): The ID of the user creating comments. If omitted, comments are created without user attribution.

Optionally include experimental_commentsOptions for metadata:

  • threadData (Record<string, any>, optional): Metadata attached to new threads when they are created by the editThreads tool.
  • commentData (Record<string, any>, optional): Metadata attached to new comments when they are created by the editThreads tool.
// JWT must include Document Server credentials
import jwt from 'jsonwebtoken'

const jwtToken = jwt.sign(
  {
    // Document Server credentials (required for comment tools)
    experimental_document_server_id: 'your-document-server-id',
    experimental_document_server_management_api_secret: 'your-document-server-management-api-secret',
  },
  TIPTAP_CLOUD_AI_SECRET,
  { expiresIn: '1h' },
)

const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  body: JSON.stringify({
    toolName: 'editThreads',
    input: {},
    schemaAwarenessData,
    // Reference the Tiptap Cloud document
    experimental_documentOptions: {
      documentId: '123',
      userId: 'ai-assistant',
    },
    // Optional metadata
    experimental_commentsOptions: {
      threadData: { source: 'ai' },
      commentData: { source: 'ai' },
    },
  }),
})

End result

The result is a simple but polished AI chatbot application:

See the source code on GitHub.

Next steps

PreviouslySchema awareness