Google Docs lets collaborators collaborate by writing
[comments](https://support.google.com/docs/answer/6033474) and making
[suggestions](https://support.google.com/docs/answer/6033474) which act as deferred edits waiting for approval.

You can use the API to view suggested changes inline within the document text.
You can also programmatically read, create, reply to, update, or delete comment
and suggestion threads.

When you use the
[`documents.get`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) method to
fetch document content, the content might include unresolved suggestions. To
control how `documents.get` represents suggestions, use the optional
[`SuggestionsViewMode`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#SuggestionsViewMode)
parameter. The following filter conditions are available with this parameter:

- Get content with `SUGGESTIONS_INLINE`, so text pending either deletion or insertion appears in the document.
- Get content as a preview with all suggestions accepted.
- Get content as a preview, without suggestions, with all suggestions rejected.

If you don't provide `SuggestionsViewMode`, the Google Docs API uses a default
setting appropriate to the current user's privileges.

To control whether comments are included when fetching a document, use the
optional
[`commentsViewMode`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get#body.QUERY_PARAMETERS.comments_view_mode)
parameter.
Comments are only returned if suggestions are returned inline. When setting
`commentsViewMode`, you must also configure
[`suggestionsViewMode`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get#body.QUERY_PARAMETERS.suggestions_view_mode)
as follows:

- If `commentsViewMode` is set to `COMMENTS_VIEW_MODE_INCLUDED`, `suggestionsViewMode` must be set to `SUGGESTIONS_INLINE`.
- If `commentsViewMode` is set to `COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS`, `suggestionsViewMode` must be set to `SUGGESTIONS_INLINE` or `DEFAULT_FOR_CURRENT_ACCESS`.

If you set `commentsViewMode` to `COMMENTS_VIEW_MODE_INCLUDED`,
you must also set `includeTabsContent` to `true`. If you use a
field mask that references the `tabs` field (or any subfield), the API
implicitly treats the request as if you set `includeTabsContent` to `true`.

## Suggestions \& indexes

One reason the `SuggestionsViewMode` is important is that the indexes in the
response might vary depending on whether there are suggestions, as shown in the
following example.

> [!WARNING]
> To obtain indexes that you can use in a subsequent [`documents.batchUpdate`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate) call, get the version using **\`SUGGESTIONS_INLINE\`**. Only this mode provides the correct indexes.

| Content with suggestions | Content without suggestions |
|---|---|
| ``` { "tabs": [ { "documentTab": { "body": { "content": [ { "startIndex": 1, "endIndex": 31, "paragraph": { "elements": [ { "startIndex": 1, "endIndex": 31, "textRun": { "content": "Text preceding the suggestion\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } }, { "startIndex": 31, "endIndex": 51, "paragraph": { "elements": [ { "startIndex": 31, "endIndex": 50, "textRun": { "content": "Suggested insertion", "suggestedInsertionIds": [ "suggest.vcti8ewm4mww" ], "textStyle": {} } }, { "startIndex": 50, "endIndex": 51, "textRun": { "content": "\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } }, { "startIndex": 51, "endIndex": 81, "paragraph": { "elements": [ { "startIndex": 51, "endIndex": 81, "textRun": { "content": "Text following the suggestion\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } } ] } } } ] }, ``` | ``` { "tabs": [ { "documentTab": { "body": { "content": [ { "startIndex": 1, "endIndex": 31, "paragraph": { "elements": [ { "startIndex": 1, "endIndex": 31, "textRun": { "content": "Text preceding the suggestion\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } }, { "startIndex": 31, "endIndex": 32, "paragraph": { "elements": [ { "startIndex": 31, "endIndex": 32, "textRun": { "content": "\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } }, { "startIndex": 32, "endIndex": 62, "paragraph": { "elements": [ { "startIndex": 32, "endIndex": 62, "textRun": { "content": "Text following the suggestion\n", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } } ] } } } ] }, ``` |

In the preceding response, the paragraph containing the line "Text following the
suggestion" shows the difference when using `SuggestionsViewMode`. With the
value set to `SUGGESTIONS_INLINE`, the `startIndex` of the
[`ParagraphElement`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#ParagraphElement)
begins at 51 and the `endIndex` stops at 81. Without suggestions, the
`startIndex` and `endIndex` range from 32--62.

## Get content without suggestions

The following partial code sample shows how to get a document as a preview with
all suggestions rejected (if there are any) by setting the `SuggestionsViewMode`
parameter to `PREVIEW_WITHOUT_SUGGESTIONS`.

### Java


```java
final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();
```

<br />

### Python


```python
SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)
```

<br />

Omitting the `SuggestionsViewMode` parameter is equivalent to providing
`DEFAULT_FOR_CURRENT_ACCESS` as the parameter value.

## Style suggestions

Documents can also have *style suggestions*. These are suggested changes to
formatting and presentation, rather than changes to content.

Unlike text insertions or deletions, these don't offset the
indexes---although they might break up a
[`TextRun`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#TextRun) into
smaller chunks---but just add annotations about the suggested style change.

One such annotation is a
[`SuggestedTextStyle`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#SuggestedTextStyle),
which consists of 2 parts:

- The `textStyle`, which describes how the text is styled after the suggested
  change, but doesn't say what changed.

- The `textStyleSuggestionState`, which indicates how the suggestion alters
  the fields of the `textStyle`.

You can see this in the following document tab extract, which includes a
suggested style change:

    [01] "paragraph": {
    [02]    "elements": [
    [03]        {
    [04]            "endIndex": 106,
    [05]            "startIndex": 82,
    [06]            "textRun": {
    [07]                "content": "Some text that does not ",
    [08]                "textStyle": {}
    [09]            }
    [10]        },
    [11]        {
    [12]            "endIndex": 115,
    [13]            "startIndex": 106,
    [14]            "textRun": {
    [15]                "content": "initially",
    [16]                "suggestedTextStyleChanges": {
    [17]                    "suggest.xymysbs9zldp": {
    [18]                        "textStyle": {
    [19]                            "backgroundColor": {},
    [20]                            "baselineOffset": "NONE",
    [21]                            "bold": true,
    [22]                            "fontSize": {
    [23]                                "magnitude": 11,
    [24]                                "unit": "PT"
    [25]                            },
    [26]                            "foregroundColor": {
    [27]                                "color": {
    [28]                                    "rgbColor": {}
    [29]                                }
    [30]                            },
    [31]                            "italic": false,
    [32]                            "smallCaps": false,
    [33]                            "strikethrough": false,
    [34]                            "underline": false
    [35]                        },
    [36]                        "textStyleSuggestionState": {
    [37]                            "boldSuggested": true,
    [38]                            "weightedFontFamilySuggested": true
    [39]                        }
    [40]                    }
    [41]                },
    [42]                "textStyle": {
    [43]                    "italic": true
    [44]                }
    [45]            }
    [46]        },
    [47]        {
    [48]            "endIndex": 143,
    [49]            "startIndex": 115,
    [50]            "textRun": {
    [51]                "content": " contain any boldface text.\n",
    [52]                "textStyle": {}
    [53]            }
    [54]        }
    [55]    ],
    [56]    "paragraphStyle": {
    [57]        "direction": "LEFT_TO_RIGHT",
    [58]        "namedStyleType": "NORMAL_TEXT"
    [59]    }
    [60] }

In the preceding sample, the paragraph consists of three text runs, starting at
lines 6, 14, and 50. Examine the middle text run:

- Line 16: There's a `suggestedTextStyleChanges` object.
- Line 18: The `textStyle` specifies various formatting.
- Line 36: The `textStyleSuggestionState` tells you that only the bold part of this specification was the suggestion.
- Line 42: The italic styling of this text run is part of the current document (and not affected by the suggestion).

Only the style features set to `true` in the `textStyleSuggestionState` are part
of the suggestion.

## Create and manage comments

You can programmatically add comments and replies, edit comments, and delete
comments or replies using the [`documents.batchUpdate`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method.

When performing batch updates involving comments or suggestions, you should monitor for potential partial failures. For more information, see [Comment and suggestion update status](https://developers.google.com/workspace/docs/api/how-tos/suggestions#update-status).

### Insert a comment

To insert a comment thread, use the [`InsertCommentRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#InsertCommentRequest)
object. You must provide the comment text contents, and an anchor location (such as a range) where the comment is attached.

The following JSON example adds a non-assigned comment thread to the specified range:

    {
      "requests": [
        {
          "insertComment": {
            "content": "This is a comment added via the API.",
            "range": {
              "startIndex": 10,
              "endIndex": 25
            }
          }
        }
      ]
    }

You can assign a comment to a specific user by providing their email in the
`assigneeEmailAddress` field:

    {
      "requests": [
        {
          "insertComment": {
            "content": "Please review this paragraph.",
            "assigneeEmailAddress": "user@example.com",
            "range": {
              "startIndex": 10,
              "endIndex": 25
            }
          }
        }
      ]
    }

### Add a reply or take action

To reply to a comment or suggestion thread, or to resolve or reopen a thread,
use [`AddCommentReplyRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#AddCommentReplyRequest).

A reply is represented by a [`Post`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#Post) object.
The `Post` object contains the reply `content` and can optionally specify a `commentAction`
(to `RESOLVE` or `REOPEN` the thread).

You can also re-assign a comment thread by specifying a new `assigneeEmail` in
the `Post` object.

The following sample replies to an existing comment thread:

    {
      "requests": [
        {
          "addCommentReply": {
            "commentId": "comment_thread_id",
            "post": {
              "content": "Replying to the comment thread."
            }
          }
        }
      ]
    }

The following sample resolves a comment thread, which does not require content:

    {
      "requests": [
        {
          "addCommentReply": {
            "commentId": "comment_thread_id",
            "post": {
              "commentAction": "RESOLVE"
            }
          }
        }
      ]
    }

The following JSON sample shows how to re-assign a comment thread:

    {
      "requests": [
        {
          "addCommentReply": {
            "commentId": "comment_thread_id",
            "post": {
              "content": "Replying to the comment thread.",
              "assigneeEmail": "user@example.com"
            }
          }
        }
      ]
    }

### Edit a post

To edit the text content of a post you authored, use [`UpdateCommentPostRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#UpdateCommentPostRequest).
You must specify the thread ID (either `commentId` or `suggestionId`), the `postId` of the post you want to edit, and the new plain text `content`.

Note that you cannot edit the head post of a suggestion thread (as those are generated by suggest-mode edits).

    {
      "requests": [
        {
          "updateCommentPost": {
            "commentId": "comment_thread_id",
            "postId": "post_id",
            "content": "This is the updated comment text."
          }
        }
      ]
    }

### Delete comments and replies

- **Delete a comment thread:** To remove an entire comment thread, use [`DeleteCommentRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#DeleteCommentRequest). You can only delete a comment thread if you're the author of the thread's head post.
- **Delete a reply:** To delete a specific reply post, use [`DeleteCommentReplyRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#DeleteCommentReplyRequest). You can only delete replies you authored. You cannot delete reply posts that contain actions or assignees.

The following sample deletes a comment thread:

    {
      "requests": [
        {
          "deleteComment": {
            "commentId": "comment_thread_id"
          }
        }
      ]
    }

## Write suggestions and manage suggestion threads

You can write edits as suggestions rather than direct edits, and programmatically accept, reject, or delete suggestion threads.

When performing batch updates involving suggestions, you should monitor for potential partial failures. For more information, see [Comment and suggestion update status](https://developers.google.com/workspace/docs/api/how-tos/suggestions#update-status).

### Create suggestions using suggest mode

To apply edits as suggestions, set the `writeMode` field of the [`WriteControl`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate#WriteControl) object to `SUGGEST` in your batch update request. All updates in the request are processed as suggestions.

    {
      "requests": [
        {
          "insertText": {
            "text": "suggested insertion text",
            "location": {
              "index": 1
            }
          }
        }
      ],
      "writeControl": {
        "writeMode": "SUGGEST"
      }
    }

#### Unsupported requests in suggest mode

When using `WriteMode.SUGGEST`, the following request types aren't supported and will return an error:

- `AddDocumentTab`
- `CreateNamedRange`
- `DeleteFooter`
- `DeleteHeader`
- `DeleteNamedRange`
- `DeleteTab`
- `UpdateDocumentTabProperties`
- `UpdateTableColumnProperties`

Additionally, you cannot suggest changes to document format or header and footer settings. In `UpdateDocumentStyle`, suggestions aren't supported for the following style types:

- `documentFormat`
- `useEvenPageHeaderFooter`
- `useFirstPageHeaderFooter`

### Accept, reject, or delete suggestion threads

You can manage suggestion threads using the following requests:

- **Accept suggestion:** Use [`AcceptSuggestionRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#AcceptSuggestionRequest) to accept the suggestion. This requires edit access to the document.
- **Reject suggestion:** Use [`RejectSuggestionRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#RejectSuggestionRequest) to reject the suggestion. This requires edit access to the document or being the author of the suggestion.
- **Delete suggestion:** Use [`DeleteSuggestionRequest`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#DeleteSuggestionRequest) to delete the suggestion. This requires being the author of the suggestion.

The following sample accepts a suggestion thread:

    {
      "requests": [
        {
          "acceptSuggestion": {
            "suggestionId": "suggestion_thread_id"
          }
        }
      ]
    }

## Comment and suggestion update status

Requests that require saving comment or suggestion threads (such as inserting comments, adding replies, or making suggestions) might experience partial failures. In these cases, the document model changes (such as text insertions or deletions) might be successfully committed to the Docs model, but the associated comments or suggestions might fail to save.

You can verify whether comment or suggestion updates were successfully applied by checking the [`commentUpdateState`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate#body.BatchUpdateDocumentResponse.FIELDS.comment_update_state) field in the [`BatchUpdateDocumentResponse`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate#body.BatchUpdateDocumentResponse).

The following states are returned in [`CommentUpdateState`](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate#CommentUpdateState):

- `NO_UPDATES_REQUESTED`: No comment or suggestion updates were requested in the batch operation.
- `ALL_SAVED`: All requested comment or suggestion updates were successfully applied.
- `ALL_FAILED_UNKNOWN_REASON`: All requested comment or suggestion updates failed to save, even though the Docs model changes might have been committed.