CommentThreadCollection

CommentThreadCollection:

{
  all(options?: CommentThreadQueryOptions): CommentThread[];
  add(input: AddCommentThreadInput): CommentThread | undefined;
}

Document-root collection for querying comment threads.

Remarks

CommentThreadCollection is the entry point for public comment thread workflows. It lives on the programmatic document root because comment threads are document-level records anchored into content.

Query results include anchored comment threads only. Orphaned top-level comment records are not exposed as public threads. Resolved comment threads are included by default, and results are ordered by the first anchor range in document order.

Examples

Query comment threads and inspect their anchors:

const threads = draft.commentThreads().all();

for (const thread of threads) {
  console.log(thread.comment.text);

  for (const range of thread.anchor.ranges) {
    console.log(range.text);
  }
}

Create a single-range text comment thread:

const paragraph = draft.body().sections()[0].content().addParagraph();
const textView = paragraph.asTextView();
textView.setText('The supplier must provide reviewed text before signing.');

const match = textView.searchText('reviewed text');
const thread = draft.commentThreads().add({
  body: 'Can Legal confirm this wording?',
  anchor: {
    type: 'text',
    ranges: [{ textView, range: match?.range }],
  },
});

Create one cross-paragraph comment thread:

const content = draft.body().sections()[0].content();
const first = content.addParagraph().asTextView();
const second = content.addParagraph().asTextView();

first.setText('First clause needs review.');
second.setText('Second clause depends on the first.');

draft.commentThreads().add({
  body: 'Review these clauses together.',
  anchor: {
    type: 'text',
    ranges: [
      { textView: first, range: first.searchText('First clause')?.range },
      { textView: second, range: second.searchText('Second clause')?.range },
    ],
  },
});

Batch comment operations in a document transaction:

await doc.transaction(async ({ draft }) => {
  for (const thread of draft.commentThreads().all({ status: 'open' })) {
    thread.reply('Checked by automated review.');
    thread.resolve();
  }

  return { commit: true };
});

Methods

all()

all(options?): CommentThread[]

Returns anchored comment threads in document order.

Parameters

options?

CommentThreadQueryOptions

Optional query filter

Returns

CommentThread[]

Anchored comment threads that match the query options

Remarks

Resolved comment threads are included by default. Pass { status: 'open' } or { status: 'resolved' } to narrow results.

Threads are ordered by their first text anchor range in document order. Anchor ranges inside a thread are also returned in document order, and replies are ordered deterministically by timestamp with a stable fallback.

---

add()

add(input): CommentThread | undefined

Creates a text-anchored comment thread.

Parameters

input

AddCommentThreadInput

Plain text comment body and text anchor input

Returns

CommentThread | undefined

The created comment thread, or undefined when creation cannot apply

Remarks

Creation returns the created thread so callers can immediately inspect, reply to, resolve, unresolve, edit, or remove it.

The SDK assigns the comment author from the current author context and assigns a creation timestamp. The public API does not accept per-operation author or timestamp overrides.

If the trimmed body is empty or the supplied anchor cannot produce a valid text anchor, this method returns undefined and leaves the document unchanged.