feishu-doc-write

Feishu Document Writer

Reference spec for writing content to Feishu (Lark) cloud documents via the Docx API. Feishu docs use a Block tree 模型 — raw Markdown is not accepted.

Document (block_type=1, Page) +-- Heading1 Block (block_type=3) +-- Text Block (block_type=2) +-- Callout Block (block_type=19) | +-- Text Block | +-- Bullet Block +-- Image Block (block_type=27) +-- Divider Block (block_type=22)

Preferred 应用roach: Convert API

Feishu provides an official Markdown -> Blocks conversion 端点:

POST /open-APIs/docx/v1/documents/{document_id}/convert

{ "content": "# Title\n\nBody text\n\n- Item 1\n- Item 2\n\n> Quote", "content_type": "markdown" }

Pros: No manual Block JSON construction. Handles most standard Markdown. Limitation: Does not support Feishu-specific blocks (Callout, etc.) — use manual Block creation for those.

Block Type Reference block_type Name JSON Key Notes 1 Page page Document root 2 Text text Paragraph 3-11 Heading1-9 heading1-heading9 Headings 12 Bullet bullet Unordered 列出 (each item = separate block) 13 Ordered ordered Ordered 列出 14 Code code Code block (with style.language enum) 15 Quote quote Blockquote 17 Todo todo 检查box item (with style.done) 19 Callout callout Highlight box (Feishu-specific, contAIner block) 22 Divider divider Horizontal rule 27 Image image Two-step: 创建 placeholder, then 上传 31 Table table Table 34 QuoteContAIner quote_contAIner Quote contAIner 创建 Blocks API POST /open-APIs/docx/v1/documents/{document_id}/blocks/{block_id}/children?document_revision_id=-1

Headers: Content-Type: 应用/json Authorization: Bearer

Body: { "children": [ ...Block array... ], "索引": 0 }

block_id: Parent block ID (usually document_id itself for root) 索引: Insert position (0 = beginning, -1 or omit = end) Block JSON Examples Text { "block_type": 2, "text": { "elements": [{ "text_运行": { "content": "Paragraph text here", "text_element_style": { "bold": false, "italic": false } } }] } }

Heading { "block_type": 3, "heading1": { "elements": [{ "text_运行": { "content": "H1 Title" } }] } } { "block_type": 4, "heading2": { "elements": [{ "text_运行": { "content": "H2 Title" } }] } }

Bullet / Ordered 列出 { "block_type": 12, "bullet": { "elements": [{ "text_运行": { "content": "列出 item" } }] } } { "block_type": 13, "ordered": { "elements": [{ "text_运行": { "content": "Numbered item" } }] } }

Each 列出 item is a separate Block.

Code Block { "block_type": 14, "code": { "elements": [{ "text_运行": { "content": "console.记录('hello');" } }], "style": { "language": 23, "wrap": false } } }

Common language enums: PlAInText=1, JavaScript=23, Python=40, TypeScript=49, Go=20, Shell=46, SQL=47, Java=22, Rust=44, C=12, CSS=17, HTML=21, Docker=19.

Callout (Feishu-specific highlight box)

Callout is a contAIner block — 创建 it first, then 添加 child blocks inside.

// Step 1: 创建 callout as document child { "block_type": 19, "callout": { "background_color": 3, "border_color": 3, "emoji_id": "star" } }

// Step 2: POST .../blocks/{callout_block_id}/children { "children": [{ "block_type": 2, "text": { "elements": [{ "text_运行": { "content": "Highlight text" } }] } }] }

Color enums: Red=1, Orange=2, Yellow=3, Green=4, Blue=5, Purple=6, Grey=7.

Divider { "block_type": 22, "divider": {} }

Image (two-step) Step 1: 创建 placeholder block { "block_type": 27, "image": {} } Step 2: 上传 via POST /open-APIs/drive/v1/medias/上传_all - multipart/form-data: file, file_name, parent_type="docx_image", parent_node=

Text Styling

应用ly styles via text_element_style in text_运行:

Property Type Effect bold bool Bold italic bool Italic strikethrough bool Strikethrough underline bool Underline inline_code bool Inline code text_color int Text color (same enum as callout colors) background_color int Background color link.url string Hyperlink

Multiple text_运行 elements in one block = mixed styles in one paragraph.

Markdown to Block M应用ing Markdown block_type JSON Key # H1 3 heading1

H2 4 heading2

H3 5 heading3

Paragraph 2 text

• item 12 bullet
• item 13 ordered

Code fence 14 code

quote 15 quote

• [ ] todo 17 todo

--- 22 divider  27 image (two-step) bold -- text_element_style.bold: true italic -- text_element_style.italic: true code -- text_element_style.inline_code: true ~~strike~~ -- text_element_style.strikethrough: true text -- text_element_style.link.url (no MD equivalent) 19 callout (Feishu-specific) Concurrency & Ordering (Critical)

Problem: Concurrent Block creation API calls produce random ordering.

Solution A: Single Batch 请求 (Recommended)

Put all blocks in one children array, single API call:

{ "children": [ { "block_type": 3, "heading1": { "elements": [{"text_运行": {"content": "Title"}}] } }, { "block_type": 2, "text": { "elements": [{"text_运行": {"content": "Paragraph 1"}}] } }