Comments API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Work through a review round on a client site

A client has finished reviewing a site and left comments across its pages. You want to pull the ones nobody has looked at yet, work down the list oldest first, and record progress as you go so a teammate picking it up later can see what's left.

To work through the comments on a site:

1. Call Query Comments, filtering on status for the comments nobody has read and sorting oldest first:

   Copy

2. Page through the results with the cursors.next value returned in pagingMetadata.

3. Call Update Comment Status with OPEN and the comment's current revision for each comment you've read but not yet handled.

4. Call Update Comment Status with RESOLVED once the comment is dealt with.

A comment you've already triaged reappears in the NEW page if the commenter replies to it, or reopens it after you've resolved it, so re-running the query picks up the threads the client has come back on.

Answer a client's feedback

A client asked a question in a comment and you want to answer it in place, so the thread stays with the point on the page it refers to.

To reply to a comment:

1. Call Get Comment to read the comment and its current revision.
2. Call Create Comment Reply with that revision and the reply text. The reply is appended to the end of replies.
3. Call Update Comment Reply with the reply's index and the comment's current revision to correct your own reply afterwards.

Moderate the replies on a comment

A reply on a comment needs to come off, whoever wrote it. Because replies are addressed by their position in the list, re-read the comment first so you're working from current indexes.

To remove a reply:

1. Call Get Comment and note the index of the reply to remove, along with the comment's revision.
2. Call Delete Comment Reply with that index and that revision.
3. Repeat from step 1 if the call fails because the comment changed in between. The call is rejected rather than applied to a different reply.

Track feedback in an external tool

You run client reviews through your own project tracker and want comments to show up there as they're left, without polling for changes.

To mirror comments into an external tool:

1. Subscribe to the Comment Created webhook to pick up each new comment as it's left.
2. Subscribe to the Comment Updated webhook to pick up status triage, changes to replies, and edits a commenter makes to their own message or commentLocation. Updated events carry the previously stored values of the changed fields, so you can tell which status a comment moved from.
3. Subscribe to the Comment Deleted webhook to remove the matching record in your tool.
4. Call Query Comments, filtering on feedbackId, to backfill an existing review round when a client first connects.

Find every comment in one feedback session

You want everything a client said in a single round of review, in the order they said it.

To retrieve the comments in a feedback session:

1. Call Query Comments, filtering on feedbackId and sorting oldest first:

   Copy

2. Page through the results with the cursors.next value returned in pagingMetadata.