Supported way to deep-link to a specific Word comment in a SharePoint document

Question

We are developing a Word Office Add-in for documents stored in SharePoint Online. We need to generate a URL that opens a document in Word Online

and navigates directly to a specific clause or paragraph.

Environment

• SharePoint Online
  • Word Online and Word desktop
  • Office.js Word API 1.4
  • Microsoft Graph v1.0
  • Organizational Microsoft 365 accounts

  Current implementation

  The add-in locates the required paragraph or content control and inserts a comment using Office.js:

  
    const comment = range.insertComment(commentText);
  
    comment.load("id");
  
    await context.sync();
  
    const commentId = comment.id;
  
  

  We retain the returned Word.Comment.id so that subsequent operations can reuse the existing comment instead of creating duplicate comments. Word.Comment documentation: https://learn.microsoft.com/en-us/javascript/api/word/word.comment We found that the following URL format consistently opens the document in Word Online and navigates directly to the comment:

  
    https://contoso.sharepoint.com/sites/Contracts/Shared%20Documents/Contract.docx
  
        ?web=1
  
        &nav=eyJjIjozODY0NDkwMTl9
  
  

  The nav value is a Base64URL-encoded representation of:

  
    {"c":386449019}
  
  

  The value of c is the comment ID returned by Office.js. Our URL-generation logic is conceptually:

  
    const navigationPayload = JSON.stringify({
  
      c: Number(commentId)
  
    });
  
    const nav = base64UrlEncode(navigationPayload);
  
    const url =
  
      `${sharePointFileUrl}?web=1&nav=${encodeURIComponent(nav)}`;
  
  

  This works directly with the SharePoint file URL. It does not require the :w:/s/... sharing-link format generated by Word Online's Copy linkcaction. Microsoft Graph supports creating DriveItem sharing links through createLink, but its documented request does not appear to support a comment, paragraph, bookmark, or other navigation target: https://learn.microsoft.com/en-us/graph/api/driveitem-createlink

  Questions

1. Is the following an officially supported Word Online deep-link format?

      
      ?web=1&nav=<Base64URL encoded {"c": <Word.Comment.id>}>
      
   

2. Can Microsoft confirm that the c property represents an Office.js Word.Comment.id?
3. Is this URL format supported for production integrations, or is the nav parameter an internal implementation detail that could change withoutcnotice?
4. Is there a documented Word, SharePoint, or Microsoft Graph API for generating this comment-specific URL instead of constructing the nav parameter ourselves?
5. Are Word.Comment.id values stable after:
   • saving and closing the document;
   • reopening it in Word Online or Word desktop;
   • creating new SharePoint document versions;
   • renaming or moving the file while retaining the same DriveItem?
6. Is there a supported alternative for navigating directly to a paragraph, bookmark, or content control without adding a comment?
7. Is comment navigation supported only in Word Online, or can a link also open Word desktop and navigate to the corresponding comment?

Answer 1

Hi,

I couldn’t find any official Microsoft documentation confirming the behavior of the nav query parameter or its payload format. Based on the public documentation:

• Word.Comment.id is documented only as the identifier used by the Office.js API for comment operations. There is no documentation stating that it corresponds to the c value in a nav payload.
• Microsoft Graph createLink generates sharing links for a DriveItem, but it doesn’t provide a way to generate links targeting a specific comment, paragraph, bookmark, or content control.
• I also couldn’t find any documentation that guarantees the stability of Word.Comment.id across save/reopen, version creation, or file move/rename operations.

Because the nav parameter isn’t documented, it should be considered an implementation detail rather than a supported public interface. Microsoft doesn’t provide compatibility guarantees for undocumented URL formats, so they may change without notice.

Likewise, I couldn’t find a documented API for generating deep links to Word comments or for navigating directly to a paragraph or content control in Word Online or Word desktop.

If your solution depends on long-term compatibility, I wouldn’t recommend relying on the undocumented nav parameter. Instead, if you need an official statement on whether this behavior is supported or intended for production integrations, I’d recommend opening a support request with Microsoft or submitting the question through the Microsoft 365 Developer support channels, as only the product team can confirm undocumented behaviors.