Notion Comments API 实战:页面与块级评论读写、Discussion 串行回复、Read/Insert 权限边界与客服工单闭环工程指南
2026 年 11 月 20 日
一、为什么 Notion 评论自动化同步经常报错 403、重复建楼或丢失上下文? #
在把 Notion 用作客服工单系统、研发需求评审或外发法务合审台账时,团队常希望把 Notion 页面里的批注实时同步到飞书、Slack 或工单后端(基础操作可先阅读 评论和提及指南)。然而在对接 Notion Comments API(Notion-Version: 2025-09-03)时,开发者最常踩中四个隐形边界:
- 权限只开了读写内容,却漏勾
Read comments与Insert comments:创建集成时(参见 创建 Notion API 集成),评论能力默认不开启;未勾选对应能力会直接返回403 restricted_resource。 - 混淆
parent.page_id与discussion_id,导致每条回复都新建一条顶级讨论:调用POST /v1/comments时,如果传parent: {"page_id": ...}会在页面顶部新起一条独立讨论;只有传入已有线程的discussion_id,才能在原讨论串下追加回复。 - 误以为 API 能对任意正文字词新建行内划词批注:Notion API 支持读取挂在特定 Block 上的未解决评论,也支持回复该 Block 既有的
discussion_id,但不支持通过 API 从零在某个段落里新建“行内划词批注”;此外,API 当前仅返回**未解决(Unresolved)**的活跃讨论。 - 单条评论超过 2000 字符报错
400 validation_error:与正文块一致,评论的rich_text数组内单个文本节点同样受限于 2000 字符上限,且高频拉取易触及每秒 3 次请求的速率限制。
| 能力维度 | 读取页面/块评论 (GET /v1/comments) | 创建页面顶层讨论 (POST /v1/comments) | 回复既有线程 (POST /v1/comments) | 客户端 UI 手动操作 |
|---|---|---|---|---|
| 核心传参 | Query 参数 ?block_id={page_or_block_id} | Body 传 "parent": {"page_id": "..."} | Body 传 "discussion_id": "..." | 划词、块左侧 ⋮⋮ 或页顶讨论区 |
| 所需集成权限 | Read comments | Insert comments | Insert comments | 页面 Can comment 及以上权限 |
| 已解决评论可见性 | 不可见(仅返回未解决活跃评论) | 不适用 | 若线程已关闭需在 UI 重开 | 可在页顶或 Updates 中随时重开 |
| 适用工程场景 | 定时巡检待闭环批注、SLA 超时提醒 | 外部系统自动推送审批/验收意见 | 客服/研发回复从飞书回写到原讨论串 | 人工精细划词审阅与关闭线程 |
二、Comments API 四步工程规范与防重复建楼策略 #
要构建稳定可靠的双向评论同步与审阅催办管道,建议严格遵循以下四步规范(评论通知降噪技巧可参阅 评论批注与 Inbox 降噪实战):
- 按最小权限矩阵授予集成能力:若脚本仅用于巡检未闭环评审意见,只勾选
Read comments;仅当需要自动回写客户回复时,才开启Insert comments,防止机器人误刷页面讨论区。 - 先用 Blocks API 遍历
has_children再并发拉取块级评论:GET /v1/comments?block_id={page_id}仅返回页面顶部讨论,不会自动吐出正文子块里的划词批注。若需全页审计,应先通过 Blocks API 递归树读取 收集页面内全部 Block ID,再按 3 req/s 节奏逐块查询,或优先约定外部评审统一使用页面顶部讨论区。 - 落库保存
discussion_id与评论id映射实现幂等回写:外部消息回写 Notion 时,先查询工单表是否已绑定discussion_id。已有则沿用discussion_id串行回复;仅有首次系统通知时才通过parent.page_id发起新线程,并在回写正文中附带外部消息指纹避免回环。 - 对超长回复做 1900 字符分片拼接:当外部 AI 摘要或报错堆栈超过 1900 字符时,应拆分为多个
rich_text元素塞入同一请求,或拆分成两条连续回复。
三、Python 实战:读取未解决评论并按 discussion_id 安全串行回写 #
以下脚本演示如何拉取页面未解决评论、按 discussion_id 聚合线程,并将外部回复安全追加到指定讨论串(含 429 Retry-After 退避与超长切片):
import os
import time
from collections import defaultdict
from typing import Any
import httpx
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2025-09-03",
"Content-Type": "application/json",
}
def notion_request(client: httpx.Client, method: str, url: str, **kwargs: Any) -> dict[str, Any]:
for attempt in range(5):
resp = client.request(method, url, headers=HEADERS, timeout=20.0, **kwargs)
if resp.status_code == 429:
time.sleep(float(resp.headers.get("Retry-After", 2 ** attempt)) + 0.25)
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError(f"Notion API 请求失败: {method} {url}")
def list_unresolved_threads(client: httpx.Client, block_id: str) -> dict[str, list[dict[str, Any]]]:
"""分页读取指定页面或块的全部未解决评论,并按 discussion_id 分组"""
threads: dict[str, list[dict[str, Any]]] = defaultdict(list)
cursor: str | None = None
while True:
params: dict[str, Any] = {"block_id": block_id, "page_size": 100}
if cursor:
params["start_cursor"] = cursor
data = notion_request(client, "GET", "https://api.notion.com/v1/comments", params=params)
for item in data.get("results", []):
threads[item["discussion_id"]].append(item)
if not data.get("has_more"):
break
cursor = data.get("next_cursor")
time.sleep(0.35)
return dict(threads)
def reply_to_discussion(client: httpx.Client, discussion_id: str, text: str) -> dict[str, Any]:
"""向既有讨论串追加回复,自动按 1900 字符分片 rich_text"""
chunks = [text[i : i + 1900] for i in range(0, len(text), 1900)] or [""]
payload = {
"discussion_id": discussion_id,
"rich_text": [{"type": "text", "text": {"content": c}} for c in chunks],
}
return notion_request(client, "POST", "https://api.notion.com/v1/comments", json=payload)
四、Formula 2.0 实战:未解决评论数与评审响应 SLA 门禁 #
在对外交付或法务合审台账中(权限边界设置参见 Can comment 与防泄密治理指南),同步脚本可将 未解决评论数(Number)、最早未回复评论时间(Date)与 评审阶段(Status)回写到数据库,并配置如下 评论 SLA 门禁 Formula 2.0 属性(更多函数详见 Formula 2.0 速查手册):
lets(
openCount, prop("未解决评论数"),
firstOpenAt, prop("最早未回复评论时间"),
stage, format(prop("评审阶段")),
waitHours, if(!empty(firstOpenAt), dateBetween(now(), firstOpenAt, "hours"), 0),
ifs(
stage == "已定稿" && openCount > 0,
style("⛔ 阻断发布:仍有 " + format(openCount) + " 条未解决批注", "red", "bold", "red_background"),
openCount > 0 && waitHours >= 24,
style("🚨 批注超时 " + format(waitHours) + "h(共 " + format(openCount) + " 条待回应)", "red", "bold", "red_background"),
openCount > 0,
style("🟠 待回应批注 " + format(openCount) + " 条 · 已等待 " + format(waitHours) + "h", "orange", "bold"),
style("🟢 评论全清零 · 可放行", "green")
)
)
若集成持续返回
403、404或查不到预期评论,请对照 Notion 常见报错与故障诊断手册 与 数据库架构设计速查 逐项排查页面授权与集成能力勾选状态。
五、生产环境高频踩坑清单与上线前核验要点 #
在将 Comments API 接入客服工单、合同法务评审或研发 Code Review 自动催办管道前,请逐项完成以下五项工程核验:
- 区分“集成机器人评论”与“真人协作者评论”,避免消息回环:
- 通过
POST /v1/comments写入的评论,其created_by.id归属当前集成机器人(或可配合展示名参数配置来源标识)。同步服务在轮询GET /v1/comments时,必须先调用GET /v1/users/me缓存机器人自身的bot_id,并在消费评论流时跳过created_by.id == bot_id的条目;否则机器人刚把飞书消息回写进 Notion,下一轮轮询又会把这条评论抽回飞书群,瞬间引发死循环刷屏。
- 通过
- 切勿指望通过 API 自动点击
Resolve关闭讨论串:- Notion 当前未向公开集成开放“将既有
discussion_id标记为 Resolved”的写接口,同时GET /v1/comments也只返回尚未解决的讨论。因此在设计客服或法务评审闭环时,应将数据库里的评审状态(Status)作为机器主状态,由人工在 Notion 界面点击Resolve收起批注气泡,再由脚本定时巡检“页顶未解决讨论数是否归零”作为放行卡点。
- Notion 当前未向公开集成开放“将既有
- 正文划词批注挂在具体 Block 上,不能只查顶层
page_id:- 许多运营同事习惯直接选中文档正文里某句话按
Cmd/Ctrl + Shift + M发起划词评论。这类评论的parent.type是block_id而非page_id。如果巡检脚本只调用GET /v1/comments?block_id={page_id},将完全漏掉正文里所有划词意见。对于长文档评审,要么统一规定外协人员在页顶Add a Discussion留言,要么先用 Blocks API 递归树读取 拉取全页子块 ID 列表并带限流退避逐块巡检。
- 许多运营同事习惯直接选中文档正文里某句话按
- 单条评论内的
@提及与附件外链校验:- 若希望通过机器人回复唤醒特定负责人,不能在
text.content里写纯文本"@张三",而必须在rich_text数组中构造"type": "mention", "mention": {"type": "user", "user": {"id": "<user_uuid>"}}对象,才能触发对方侧边栏Inbox提醒;若评论需附带截图或工单附件,建议先通过文件直传生成受控资产或写入稳定 HTTPS 外链,避免使用临时鉴权 URL 导致几天后裂图。
- 若希望通过机器人回复唤醒特定负责人,不能在
- 警惕页面权限降级或集成被移出授权范围引发的静默失败:
- 当某个项目页面被团队空间管理员调整为私有或移除了外部集成的
Connections授权时,GET /v1/comments会立即返回404 object_not_found(而非403)。同步队列应把404归类为“授权缺失或页面已进废纸篓”告警并暂停重试,切忌在死信队列里无限空转消耗额度。
- 当某个项目页面被团队空间管理员调整为私有或移除了外部集成的
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南A
完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。