Word documents

Reading one

A Word document that arrives in chat or on an email is read automatically: its text is in front of the employee before it calls anything. That covers "what does this contract say?". Changing the document needs more than text, because an edit has to name where it goes — and that is what read_docx adds.

It returns every paragraph and table cell with an id, alongside any form fields the document declares. Paragraph ids run p1, p2, … in document order; table cells are t1r2c3; anything outside the main body carries its part as a prefix, like header1:p2. Headers, footers, footnotes and comments are read by default, because a questionnaire's answer boxes are often in a header and a reader that skipped those would call the document empty.

Editing one

edit_docx takes a list of operations and returns a new attachment. Everything it was not asked about comes back byte for byte — the fonts, the numbering, the styles, the revision ids Word hangs off each element. That matters because the document under the pen usually belongs to somebody else, and a form that comes back in a different typeface announces that a machine filled it.

• set_paragraph replaces a paragraph's text, keeping the run formatting it already had. This is how an answer goes onto a blank line.
• insert_paragraph adds paragraphs beside an existing one and inherits its formatting, so a bullet added under an answer is a bullet. Pass an array to add several at once.
• set_table_cell rewrites a cell — most questionnaires are a table with a question column and an empty one beside it.
• set_field fills a declared form field: a modern content control or a Word 97 form field, including checkboxes and dropdowns. A dropdown only accepts one of its own options.
• replace_text swaps text wherever it appears, and within confines that to one paragraph, cell or table — which is how you tick the box on one line without touching the identical boxes on every other question.
• append_paragraph and delete_paragraph for the rest.

// 1. read the questionnaire
read_docx({ attachmentId })
// → blocks include
//   { id: "p3", kind: "paragraph", text: "1. Does the solution support SSO?" }
//   { id: "p4", kind: "paragraph", text: "" }          // the blank the answer goes on
//   { id: "p10", kind: "paragraph", text: "Will be implemented at go-live?" }

// 2. answer every question in one call
edit_docx({
  attachmentId,
  operations: [
    { op: "set_paragraph", id: "p4", text: "Answer:  Yes. SAML 2.0 and OIDC are both supported." },
    { op: "insert_paragraph", after: "p4", text: [
      "\u2022 Memorial Hermann operates as the Identity Provider.",
      "\u2022 SCIM 2.0 handles provisioning and de-provisioning.",
    ] },
    { op: "replace_text", within: "p10", find: "go-live?", replace: "go-live?  Already live." },
  ],
})
// → { attachment: { id, filename: "MSS_blank-edited.docx" }, applied: [...] }

Writing a new one

create_docx builds a document from Markdown. Headings, bullet and numbered lists, tables, quotes, code blocks, bold, italic and links all become real Word constructs — a heading is Heading1, a list carries a numbering definition, a table is a table — so the recipient gets something they can restyle and keep working in rather than a text file with hashes in it.

create_docx({
  filename: "q3-security-review.docx",
  title: "Q3 Security Review",
  markdown: [
    "# Q3 Security Review",
    "",
    "SSO enforcement and encryption at rest are **complete**.",
    "",
    "| Control | Status | Owner |",
    "| --- | :---: | --- |",
    "| Encryption at rest | Done | Platform |",
    "| Pen test | In progress | Security |",
  ].join("\n"),
})
// → { attachment: { id, filename: "q3-security-review.docx" } }

To change a document that already exists, use edit_docx instead. Rewriting it from Markdown would discard the formatting the original arrived with.

What counts as a Word document

.docx, .docm, .dotx and .dotm all work. The old binary .doc does not — it is a different format entirely, and an employee handed one says so and asks for a re-save rather than reporting an empty document. The same goes for a spreadsheet or a presentation opened by mistake: the refusal names what the file actually is.

Getting the file in and out

All three tools work with an attachmentId: a file a teammate uploaded into chat, one opened off an email with read_mail_attachment, or one pulled from the web with download_web_file. The edited or created document comes back as a new attachment, and its id goes straight onto a reply through Email, or to a teammate with send_chat_attachment. The original is never modified.

For a form that arrived as a PDF rather than a Word file, see PDF forms. For a document that needs a signature rather than answers, see Document signing.