Manage comments and replies

Comments are user-provided feedback on a file, such as a reader of a word-processing document suggesting how to rephrase a sentence. There are two types of comments: anchored comments and unanchored comments. An anchored comment is associated with a specific location, such as a sentence in a word-processing document, within a specific version of a document. Conversely, an unanchored comment is just associated with the document.

Note: On blob files, the Google Drive API only supports unanchored comments. Anchored comments on blob files or Google Docs editor files aren't supported.

Replies are attached to comments and represent a user's response to the comment. The Drive API lets your users add comments and replies to documents created by your app. Collectively, a comment with replies is known as a discussion.

Add an unanchored comment

To add an unanchored comment to a document, call the comments.create method with the fileId parameter and a comments resource containing the comment.

The comment is inserted as plain text, but the response body provides an htmlContent field containing content formatted for display.

Important: We recommend you check that a user has the correct permissions to add comments. Further, only the creator of a comment or a reply can delete or edit a comment or a reply. Errors occur when a user in a non-creator role tries to delete or edit a comment. To avoid these errors, check the author.me field of the comments resource to make sure the user making the request is the author of the comment and then verify their permissions relative to the comment.

Add a reply to a comment

To add a reply to a comment, call the replies.create method with the comment, fileId parameter, and a replies resource containing the reply.

The reply is inserted as plain text, but the response body provides an htmlContent field containing content formatted for display.

Add an anchored comment to the latest revision of a document

When you add a comment, you might want to anchor it to a region in the file. An anchor defines the file revision and region in a file to which a comment refers. The comments resource defines the anchor field as a JSON string.

Note: On blob files, the Drive API only supports unanchored comments. Anchored comments on blob files or Google Docs editor files aren't supported.

Important: Anchors are immutable, and their position relative to the content of a document cannot be guaranteed between revisions. We recommend you use anchors in documents where the position doesn't change, such as image files or read-only documents.

To add an anchored comment:

1. (Optional). Call the revisions.list method to list every revisionID for a document. Only follow this step if you want to anchor a comment to any revision other than the latest revision. If you want to use the latest revision, use head for the revisionID.

2. Call the comments.create method with the fileID parameter, a comments resource containing the comment, and a JSON anchor string containing the revisionID (r) and region (a).

How you define a region depends on the type of document content you are working with. For further information, refer to Define a region.

Note: We recommend you check that a user has the correct permissions to add comments. Further, only the creator of a comment or a reply can delete or edit a comment or a reply. Errors occur when a person in a non-creator role tries to delete or edit a comment. To avoid these errors, check the author.me field of the comments resource.

Define a region

As mentioned earlier, the JSON anchor string contains a revisionID (r) and region (a). The region (a) is a JSON array containing region classifiers specifying the format and location to which a comment is anchored. A classifier might be a two-dimensional rectangle for an image, a line of text in a document, or a time duration in a video. To define a region, select the region classifier that matches the type of content you are trying to anchor to. For example, if your content is text, you are likely going to use either the txt or line region classifier.

For a list of region classifiers in the Drive API, refer to Region classifiers.

The following example shows a JSON anchor string that anchors comments to lines in two separate areas of a document:

• The first area starts at line 12 ('n':12) and extends for three lines ('l':3).
• The second area only covers line 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Replace REVISION_ID with head or the ID of a specific revision.

Important: If your app lets users update and share multiple revisions of a document, comments on older revisions might no longer apply to the anchored location. Therefore, you must indicate to which revision each comment belongs clearly in your UI.

Resolve a comment

Use the comment.update method to set the resolved property in the comments resource to true when a comment has been addressed.

When your app sets the resolved property to true, your UI should indicate that the comment has been addressed. For example, your app might:

• Disallow further replies and dim all previous replies plus the original comment.
• Hide resolved comments.

Delete a comment

Use the comments.delete method to delete comments. When a comment is deleted, Drive marks the comment resource as "deleted": "true".

List comments

Use the comments.list method to list comments. If you want to include deleted comments in the results, set the includedDeleted field to true.