Document apiReferenceHyperlinks

hyperlinks.wrap

Wrap an existing text range with a hyperlink. A range inside one pending tracked insertion is linked without authoring a revision: the insertion keeps its author and date and is split at the range boundaries. Ranges that cross a revision boundary or touch deleted, moved or several revisions are refused.

mutates documentdry runconditional
doc.hyperlinks.wrap(…)

Expected result

Returns a HyperlinkMutationResult with the created hyperlink address on success, or a failure code on no-op or an unsupported revision context.

Inputs

targetTextAddressrequired
Fields
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
blockIdstringrequired
rangeRangerequired
Fields
startintegerrequired
endintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
linkobjectrequired
Fields
destinationobjectrequired
Fields
hrefstring
anchorstring
docLocationstring
tooltipstring
targetstring
relstring

Browser relationship tokens kept for the current editing session; not persisted in DOCX or reviewed by Word.

Result

Output fields
true
status"NO_OP"
changeTagstring

Caller correlation for this commit only; never persisted or replayed on Undo/Redo.

temporaryobject
Fields
idstringrequired
phase"begin" | "replace" | "rollback" | "commit"required
tagstringrequired
onNativeEdit"cancel" | "preserve"
cancelledBy"native-edit"
appliedChangeMode"direct" | "tracked"
idstring
insertedEntityAddress[]
updatedEntityAddress[]
removedEntityAddress[]
invalidatedRefsAffectedRef[]
remappedRefsAffectedRefRemapping[]
affectedStoriesStoryLocator[]
textRangeShiftsTextRangeShift[]
trackedTextRangeShiftsTrackedTextRangeShift[]
txIdstring
warningsReviewWarning[]
effectsReceiptEffects
Fields
insertedTextTextMutationEffect[]
insertedBlocksBlockMutationEffect[]
resultTextTextTarget
Fields
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
segmentsTextSegment[]required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpaceTextCoordinateSpace
trackedChangeRefsTrackedChangeAddress[]
trackedChangeCountinteger
changedboolean
successtruerequired
hyperlinkobjectrequired
Fields
kind"inline"required
nodeType"hyperlink"required
anchorInlineAnchorrequired
Fields
startPositionrequired
endPositionrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
hyperlinkNodeIdstring | null
partsCreatedstring[]
partsModifiedstring[]
createdRIdstring
false
successfalserequired
failureobjectrequired
Fields
code"NO_OP" | "INVALID_TARGET" | "TARGET_NOT_FOUND" | "CAPABILITY_UNAVAILABLE"required
messagestringrequired
detailsobject

Failures

Pre-apply throws

  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • INVALID_TARGET
1 more codes
  • INVALID_INPUT

Non-applied receipt codes

  • NO_OP
  • INVALID_CONTEXT

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas