Manage Comments and Discussions

The Drive API allows you to add comments to files in Google Drive. You can let your users insert comments and replies in shared files and carry on discussion threads in the comments. By supporting these features in your app, you create an environment where users can share files and edit them collaboratively.

Working with comments and replies

When working with comments, you'll be interacting a lot with the comments and replies collections in addition to the files resource. In this model, a comment starts a discussion within a file, and replies are associated with a particular comment. Apps insert the content of both comments and replies as plain text, and then the response body provides an htmlContent field containing formatted content for display.

See the API reference for details and examples on using these resources.

Generally, an app must make the following API calls when managing comments:

1. A files.get call any desired file metadata or content.
2. A revisions.get call to get the revision of the file that you're currently working with. Use revisions.get(revisionId='head') to make sure you are working with the latest revision. You'll need the revision id to work with "anchors" (described below).
3. A comments.list call to retrieve the comments and replies in a file.
4. A comments.insert call to add the comment, or replies.insert to add a reply to an existing discussion.

When inserting a comment, you'll need to consider anchoring the comment to a region in the file. Reference information for anchors is provided below in this page, along with some tips on creating custom schemas.

Anchoring comments

An anchor defines the location or region in a file to which a comment relates or refers. Anchors are tied to a specific revision of a file.

Important: Anchors are immutable, and their positioning relative to the content of a document can't be guaranteed between revisions. We recommend using them in files where the position won't change (such as images) or in read-only files.

Anchors are tied to different regions for different types of files, and apps should support regions that make sense for the file types they manipulate. For example, anchoring comments to line numbers makes sense for plain text documents, while anchoring them to a horizontal and vertical position makes more sense for images.

Each anchor has two required properties:

• r — A string ID indicating which revision of the file this anchor was created for. Use the revision id retrieved with revisions.get.
• a — The region or regions associated with the anchor. This must be a JavaScript array, and the type of object in that array is a region.

You can define a region as an object with one or more region classifiers. Each region classifier is keyed by the classifier's name, and has a value containing various properties suitable for that classifier. For example, anchoring comments by lines in a document might look like the following:

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

This anchors a comment in two separate areas: at line 12 covering a range of 3 lines, and covering line 18 as well. Text content for such a comment might be, "These lines are unnecessary. They are both covered by the text in line 4."

Supported region classifiers

Choose the region classifiers most suitable for your file type. Drive supports multiple classifiers for a single region. However, you can't set the same region classifier twice in the same region.

rect

A rectangle in a two dimensional image.

Property	Description	Type
x	Position on the x axis, units default to pixels for images and percent for PDFs.	Double
y	Position on the y axis, units default to pixels for images and percent for PDFs.	Double
w	Length on the x axis, units default to pixels for images and percent for PDFs.	Double
h	Length on the y axis, units default to pixels for images and percent for PDFs.	Double
mw	The full width of the document at the time when the comment was made. This can be used to make x and w unitless since they can act like a percentage.	Double
mh	The height width of the document at the time when the comment was made. See mw above for purpose.	Double
r	The degrees of rotation of the document. E.g. if an image is rotated 90 degrees clockwise then a rectangle at 0,0 would be displayed in the top right of the displayed image. Should be one of 0, 90, 180, 270	Double

page

A page number in a pdf or tiff or other document with pages. Should also be used for documents with page-like elements. Eg. sheet (for spreadsheets), slide, layer etc.

Property	Description	Type
p	The page number (0-indexed).	Integer
mp	The number of pages in this document.	Integer

time

A duration of time in a video or other document with a time dimension | Integer

Property	Description	Type
t	The start time.	hh:MM:ss.frac formatted time string (where M = minutes, m = millis, hours and minutes are optional)
d	The duration of the time range.	hh:MM:ss:mmm formatted time string (where M = minutes, m = millis)
md	The full time duration of the document.	hh:MM:ss:mmm formatted time string (where M = minutes, m = millis)

txt

A range of text

Property	Description	Type
o	Start offset (character offset from the start of the file).	Integer
l	The length of the text range.	Integer
ml	The length of this document in characters.	Integer

line

A specific line in a text file or any files with lines in it.

Property	Description	Type
n	Line number.	Integer
l	The length of the line range.	Integer
ml	The maximum number of lines in the file.	Integer

matrix

A location in a matrix-like structure. Useful for defining row and columns in spreadsheet documents, or any other documents which have a row/column structure.

Property	Description	Type
c	The column number.	Integer
r	The row number.	Integer
w	The number of columns.	Integer
h	The number of rows.	Integer
mw	The Maximum width.	Integer
mh	The Maximum height.	Integer

Custom schemas

If you want to create a new class of region, you should namespace it by the app ID. For example, if your app has ID 1234 and creates a property called Slide, then the full classifier name would be 1234.Slide. That way if another app publishes another Slide, then the two would not collide. The blank namespace should only be used by Google-published classifiers.

Best practices for working with discussions

There are a few things to keep in mind when working with discussions: check permissions, resolve comments in some visible way, and don't display deleted comments unless you have a compelling reason to do so.

Permissions checks

Though it is not strictly required for managing comments, checking permissions is highly recommended. Only the creator of a comment or reply can delete or edit a comment, and an app will receive errors if it tries to allow any other users to perform these operations. You can avoid error scenarios by checking the author.me field of a comments resource.

UI for resolved comments

If your app sets the resolved property when inserting comments and replies, then your UI should give some clear indication of this status for users. For instance, resolved comments could be greyed out, or (like in Google documents) resolved comment threads could just be removed from the displayed file.

Important: If your app lets users update and share multiple revisions of a file, comments on older revisions may no longer apply to the anchored location. Try to give a clear indication of this in your UI to avoid confusing users.

Tombstones and deleted comments

When a user deletes a comment, Google Drive stores a "tombstone" of the comment, marked with "deleted": "true" in the comments resource. If your app retrieves some tombstoned comments with comments.list, you probably shouldn't display them to the end user.

The Drive API provides the includedDeleted property for comments.list for exception cases. In particular, apps may want to use includedDeleted to make sure that the UI displays a current comments list, without any deleted comments. The flow for this might look like the following:

1. On load, list all comments except, of course, deleted ones (the default for includedDeleted is false). Store the current time right before you send this list request.
2. Periodically perform a new list action and pass the saved timestamp as the updatedMin parameter to get the comments since your last request. In this case, set includeDeleted=true so that you can perform a diff between the existing and new comments lists.
3. Based on that diff, update the UI to clear out newly deleted comments.

Tips and tricks

To learn more about comments and discussions, you can watch the following video of Google engineers discussing related tips and tricks.