Block element data structure

An online document is a tree composed of multiple block elements. Different types of BlockElement can nest different types of elements inside. For example, a Callout block can nest any BlockElement, but a Paragraph block can only nest InlineElement. The data structure of a single block element is as follows:

{
  "blockType": enum(BlockType),             // Block element type. See the `BlockType` enum at the bottom of this document.
  /**
   * The following are all supported Block types, such as Heading and Paragraph.
   * Each Block type has its own property.
  */
  "blockquote": Object(Callout),
  "callout": Object(Callout),
  "columns": Object(Columns),
  "heading": Object(Heading),
  "paragraph": Object(Paragraph),
  "orderedList": Object(OrderedList)
  "unorderedList": Object(UnorderedList),
  "table": Object(Table),
  // Each Block type has its own supported BlockChildren. See the `children` description under each Block type.

  "children": BlockChildren[ ],

}

An online document is a tree structure composed of multiple block elements. Different types of block elements support different types of nested child elements:

The children of callout and columns must be a BlockElement array.
The children of paragraph, heading, orderedList, unorderedList, and blockquote must be an InlineElement array.
table does not currently support specifying children.

BlockType enum

Enum value	Description
paragraph	Paragraph block.
heading	Heading block.
blockquote	Quote block.
callout	Callout block.
columns	Columns block.
orderedList	Numbered list block.
unorderedList	Bulleted list block.
table	Spreadsheet block.
tableRow	Table row block (child of a table block).
tableCell	Table cell block (child of a table block).

Unsupported element types uniformly return Undefined.

Paragraph

{
  "blockType": "paragraph",
  "paragraph": {
    "text": "Paragraph text content",
    "indent": { "left": 32 },
    "folded": false
  },
  "children": [InlineElement]
}

Field name	Type	Required	Description
text	string	No	Text content of the paragraph.
indent	object(Indent)	No	Indent value. `left` must be an integer greater than 0.
folded	boolean	No	Whether to fold the paragraph (folds block elements with an indent value greater than the current paragraph).

children: InlineElement array.
The paragraph object cannot be omitted. When the content is empty, pass {}.

Heading

{
  "blockType": "heading",
  "heading": {
    "level": 1,
    "text": "Level 1 heading"
  },
  "children": [InlineElement]
}

Field name	Type	Required	Description
text	string	No	Text content of the heading.
level	integer(enum)	No	Heading level. Value range: `1` to `6`. 1 indicates a level 1 heading.

children: InlineElement array.

Quote

{
  "blockType": "blockquote",
  "blockquote": {
    "text": "Quoted content",
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

Field name	Type	Required	Description
text	string	No	Text inside the quote.
indent	object(Indent)	No	Specific indent value.

children: InlineElement array.

Callout block

{
  "blockType": "callout",
  "callout": {
    "sticker": "灯泡",
    "showstk": true,
    "color": "#333333",
    "border": "#FFD700",
    "bgcolor": "#FFF9C4"
  },
  "children": [BlockElement]
}

Field name	Type	Required	Description
sticker	string(enum Emoji)	No	Emoji code. See Emoji enum values.
showstk	boolean	No	Whether to display the emoji.
color	string	No	Text color.
border	string	No	Border color.
bgcolor	string	No	Background color.

children: BlockElement array (InlineElement is not allowed).

Columns

{
  "blockType": "columns",
  "columns": {
    "size": 2,
    "noFill": false
  },
  "children": [BlockElement]
}

Field name	Type	Required	Description
size	number	No	Number of columns.
noFill	boolean	No	Whether to automatically fill the background color.

children: BlockElement array (InlineElement is not allowed).

Numbered list

{
  "blockType": "orderedList",
  "orderedList": {
    "list": {
      "listId": "list-001",
      "level": 0,
      "listStyleType": "decimal",
      "listStyle": {
        "format": "decimal",
        "text": "%1.",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

Field name	Type	Required	Description
list	object(ListObject)	Yes	Specific attributes of the numbered list. See ListObject.
indent	object(Indent)	No	Indent value. `left` must be an integer greater than 0.

children: InlineElement array.

Bulleted list

{
  "blockType": "unorderedList",
  "unorderedList": {
    "list": {
      "listId": "list-002",
      "level": 0,
      "listStyleType": "disc",
      "listStyle": {
        "format": "disc",
        "text": "%1",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

Field name	Type	Required	Description
list	object(ListObject)	Yes	Specific attributes of the bulleted list. See ListObject.
indent	object(Indent)	No	Indent value. `left` must be an integer greater than 0.

children: InlineElement array.

Spreadsheet

{
  "blockType": "table",
  "table": {
    "rolSize": 3,
    "colSize": 4,
    "cells": [
      ["Row1-Col1", "Row1-Col2", "Row1-Col3", "Row1-Col4"],
      ["Row2-Col1", "Row2-Col2", "Row2-Col3", "Row2-Col4"],
      ["Row3-Col1", "Row3-Col2", "Row3-Col3", "Row3-Col4"]
    ]
  }
}

Field name	Type	Required	Description
rolSize	number	Yes	Number of rows.
colSize	number	Yes	Number of columns.
cells	String[][]	No	Cell text content. A two-dimensional String array.

children: Not supported. Specifying children is not currently allowed.

InlineElement data structure

Inline elements are used in the children of text-based block elements (paragraphs, headings, lists, and so on).

InlineType enum

Enum value	Description
text	Text.
sticker	Emoji.
image	Image.
link	Link.

Text

{
  "text": "Bold red text",
  "sz": 16,
  "color": "red",
  "highlight": "yellow",
  "bold": true,
  "italic": false,
  "stike": false,
  "underline": false,
  "fonts": "monospace"
}

Field name	Type	Required	Description
text	string	Yes	Text content.
sz	number	No	Font size (default unit: px).
color	string	No	Text color.
highlight	string	No	Highlight background color.
bold	boolean	No	Whether to apply bold.
italic	boolean	No	Whether to apply italic.
stike	boolean	No	Whether to apply strikethrough.
underline	boolean	No	Whether to apply underline.
fonts	string(enum Fonts)	No	Font. Enum values: - monospace: monospace font - STSong: STSong - Microsoft YaHei: Microsoft YaHei - FangSong_GB2312: FangSong GB2312 - Helvetica: Helvetica - Helvetica Neue: Helvetica Neue - Consolas: Consolas - 宋体: SimSun - Impact: Impact - sanrif: sanrif - Calibri: Calibri

Emoji

{
  "elementType": "sticker",
  "properties": {
    "code": "大笑"
  }
}

Field name	Type	Required	Description
code	string(enum Emoji)	Yes	Emoji code. See Emoji enum values.

Image

{
  "elementType": "image",
  "properties": {
    "src": "https://example.com/image.jpg"
  }
}

Field name	Type	Required	Description
src	string	No	Image resource URL.

Link

{
  "elementType": "link",
  "properties": {
    "href": "https://example.com"
  },
  "children": [
    { "text": "Click to open the link" }
  ]
}

Field name	Type	Required	Description
href	string	No	Link URL.

children: Text array. When inserting a link, children must be specified and contain at least one text node whose text is not empty.

Common data structures

Indent

Field name	Type	Required	Description	Example
left	number	No	Specific indent value. Must be an integer greater than 0, otherwise an error is returned.	`32`

ListObject

Field name	Type	Required	Description
listId	string	No	ID of the current list. When inserting a multi-level numbered list, ensure that `listId` is consistent across the same group of multi-level lists, otherwise the display will be incorrect.
level	number	Yes	List tier (starting from 0).
listStyleType	string	Yes	List style type.
listStyle	object(ListStyle)	Yes	Specific list style. See ListStyle.
symbolStyle	object(SymbolStyle)	No	Style of the list symbol. See SymbolStyle.

ListStyle

Field name	Type	Required	Description
format	string	Yes	Bullet list format.
text	string	Yes	Text.
align	string	Yes	Alignment, such as `left`, `center`, or `right`.

SymbolStyle

Field name	Type	Required	Description
sz	number	No	Font size of the bullet list symbol.
shd	string	No	Background color of the bullet list symbol.
fonts	string	No	Font format of the bullet list symbol.
color	string	No	Font color of the bullet list symbol.
bold	boolean	No	Whether to apply bold.
strike	boolean	No	Whether to display strikethrough.
italic	boolean	No	Whether to display italic.

Emoji enum values (complete list of emoji codes)

The following enum values can be used for callout.sticker and the inline emoji element sticker.properties.code.

Emoji	Emoji	Emoji	Emoji
`优先级: 1` // Priority: 1	`优先级: 2` // Priority: 2	`优先级: 3` // Priority: 3	`优先级: 4` // Priority: 4
`优先级: 5` // Priority: 5	`优先级: 6` // Priority: 6	`优先级: 7` // Priority: 7	`进度: 未开始` // Progress: Not started
`进度: 20%` // Progress: 20%	`进度: 40%` // Progress: 40%	`进度: 50%` // Progress: 50%	`进度: 70%` // Progress: 70%
`进度: 90%` // Progress: 90%	`进度: 已完成` // Progress: Completed	`微笑` // Smile	`憨笑` // Grin
`大笑` // Laugh	`加油` // Cheer	`色` // Drool	`偷笑` // Snicker
`跳舞` // Dance	`捂脸哭` // Facepalm cry	`笑哭` // Laughing tears	`流泪` // Tear
`疑问` // Question	`傻笑` // Silly grin	`流鼻血` // Nosebleed	`狗子` // Doggy
`赞` // Thumbs up	`OK`	`抱拳` // Cupped hands	`向上` // Up
`向下` // Down	`向左` // Left	`向右` // Right	`资料` // Profile
`本子` // Notebook	`笔记本` // Laptop	`折线图` // Line	`柱状图` // Column
`羽毛笔` // Quill	`钢笔` // Pen	`警告` // Warning	`问号` // Question mark
`禁止` // Forbidden	`禁行` // No entry	`锁` // Lock	`气泡` // Speech bubble
`沙漏` // Hourglass	`公文包` // Briefcase	`火箭` // Rocket	`火` // Fire
`奖牌` // Medal	`灯泡` // Lightbulb	`钉子` // Nail	`旗子` // Flag
`茶` // Tea	`休假` // Vacation	`气球` // Balloon	`锦鲤` // Koi
`咖啡` // Coffee	`奶茶` // Milk tea	`调色板` // Palette	`感谢` // Thanks
`打招呼` // Wave	`666`	`握手` // Handshake	`胜利` // Victory
`一点点` // A little	`鼓掌` // Applause	`送花花` // Send flowers	`比心` // Finger heart
`加一` // +1	`100分` // 100 points	`KPI`	`对勾` // Check
`爱心` // Heart	`可爱` // Cute	`发呆` // Stunned	`老板` // Boss
`害羞` // Shy	`闭嘴` // Zip it	`睡` // Sleep	`大哭` // Bawl
`尴尬` // Awkward	`调皮` // Mischievous	`惊讶` // Surprised	`流汗` // Sweat
`广播` // Broadcast	`自信` // Confident	`你强` // You rock	`怒吼` // Roar
`惊愕` // Shocked	`快哭了` // About to cry	`无聊` // Bored	`吐` // Puke
`算账` // Settle accounts	`晕` // Dizzy	`摸摸` // Pat	`飞吻` // Blow kiss
`鄙视` // Disdain	`嘘` // Shush	`思考` // Think	`亲亲` // Kiss
`感冒` // Cold	`对不起` // Sorry	`再见` // Goodbye	`投降` // Surrender
`哼` // Hmph	`欠扁` // Asking for it	`坏笑` // Sly smile	`拜托` // Please
`可怜` // Pitiful	`舒服` // Comfy	`爱意` // Love	`财迷` // Money lover
`迷惑` // Confused	`PK`	`委屈` // Aggrieved	`灵感` // Inspiration
`天使` // Angel	`鬼脸` // Ghost face	`凄凉` // Forlorn	`郁闷` // Gloomy
`吃瓜` // Watching drama	`嘿嘿` // Hehe	`抠鼻` // Nose pick	`呲牙` // Toothy grin
`彩虹` // Rainbow	`耶` // Yay	`捂眼睛` // Cover eyes	`推眼镜` // Push glasses
`暗中观察` // Watching quietly	`开心` // Happy	`惊喜` // Surprise	`回头` // Look back
`发怒` // Angry	`忍者` // Ninja	`衰` // Unlucky	`脑暴` // Brainstorm
`冷笑` // Smirk	`黑眼圈` // Dark circles	`恭喜` // Congrats	`费解` // Puzzled
`收到` // Received	`炸弹` // Bomb	`白眼` // Eye roll	`一团乱麻` // Mess
`无奈` // Helpless	`敲打` // Knock	`专注` // Focused	`忙疯了` // Swamped
`鞠躬` // Bow	`摊手` // Shrug	`抱抱` // Hug	`举手` // Raise hand
`跪了` // Kneel	`猫咪` // Kitty	`二哈` // Husky	`三多` // Sanduo
`承让` // You let me win	`撒花` // Confetti	`邮件` // Mail	`文档` // Document
`演示` // Presentation	`表格` // Spreadsheet	`生日快乐` // Happy birthday	`心碎` // Heartbreak
`红包` // Red packet	`嘴唇` // Lips	`鲜花` // Fresh flower	`残花` // Wilted flower
`干杯` // Cheers	`出差` // Business trip	`时间` // Time	`福` // Fortune
`月饼` // Mooncake	`礼物` // Gift	`幼苗` // Sprout	`烟花` // Fireworks
`灯笼` // Lantern	`爆竹` // Firecracker	`鸡腿` // Chicken leg	`高铁` // High-speed rail
`三连` // Triple combo	`OKR`	`Done`

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

Block element data structure