Notion Comments API 实战:页面与块级评论读写、Discussion 串行回复、Read/Insert 权限边界与客服工单闭环工程指南

2026 年 11 月 20 日

一、为什么 Notion 评论自动化同步经常报错 403、重复建楼或丢失上下文? #

在把 Notion 用作客服工单系统、研发需求评审或外发法务合审台账时,团队常希望把 Notion 页面里的批注实时同步到飞书、Slack 或工单后端(基础操作可先阅读 评论和提及指南)。然而在对接 Notion Comments API(Notion-Version: 2025-09-03)时,开发者最常踩中四个隐形边界:

  1. 权限只开了读写内容,却漏勾 Read comments 与 Insert comments:创建集成时(参见 创建 Notion API 集成),评论能力默认不开启;未勾选对应能力会直接返回 403 restricted_resource。
  2. 混淆 parent.page_id 与 discussion_id,导致每条回复都新建一条顶级讨论:调用 POST /v1/comments 时,如果传 parent: {"page_id": ...} 会在页面顶部新起一条独立讨论;只有传入已有线程的 discussion_id,才能在原讨论串下追加回复。
  3. 误以为 API 能对任意正文字词新建行内划词批注:Notion API 支持读取挂在特定 Block 上的未解决评论,也支持回复该 Block 既有的 discussion_id,但不支持通过 API 从零在某个段落里新建“行内划词批注”;此外,API 当前仅返回**未解决(Unresolved)**的活跃讨论。
  4. 单条评论超过 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 降噪实战):

  1. 按最小权限矩阵授予集成能力:若脚本仅用于巡检未闭环评审意见,只勾选 Read comments;仅当需要自动回写客户回复时,才开启 Insert comments,防止机器人误刷页面讨论区。
  2. 先用 Blocks API 遍历 has_children 再并发拉取块级评论:GET /v1/comments?block_id={page_id} 仅返回页面顶部讨论,不会自动吐出正文子块里的划词批注。若需全页审计,应先通过 Blocks API 递归树读取 收集页面内全部 Block ID,再按 3 req/s 节奏逐块查询,或优先约定外部评审统一使用页面顶部讨论区。
  3. 落库保存 discussion_id 与评论 id 映射实现幂等回写:外部消息回写 Notion 时,先查询工单表是否已绑定 discussion_id。已有则沿用 discussion_id 串行回复;仅有首次系统通知时才通过 parent.page_id 发起新线程,并在回写正文中附带外部消息指纹避免回环。
  4. 对超长回复做 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 自动催办管道前,请逐项完成以下五项工程核验:

  1. 区分“集成机器人评论”与“真人协作者评论”,避免消息回环:
    • 通过 POST /v1/comments 写入的评论,其 created_by.id 归属当前集成机器人(或可配合展示名参数配置来源标识)。同步服务在轮询 GET /v1/comments 时,必须先调用 GET /v1/users/me 缓存机器人自身的 bot_id,并在消费评论流时跳过 created_by.id == bot_id 的条目;否则机器人刚把飞书消息回写进 Notion,下一轮轮询又会把这条评论抽回飞书群,瞬间引发死循环刷屏。
  2. 切勿指望通过 API 自动点击 Resolve 关闭讨论串:
    • Notion 当前未向公开集成开放“将既有 discussion_id 标记为 Resolved”的写接口,同时 GET /v1/comments 也只返回尚未解决的讨论。因此在设计客服或法务评审闭环时,应将数据库里的 评审状态(Status)作为机器主状态,由人工在 Notion 界面点击 Resolve 收起批注气泡,再由脚本定时巡检“页顶未解决讨论数是否归零”作为放行卡点。
  3. 正文划词批注挂在具体 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 列表并带限流退避逐块巡检。
  4. 单条评论内的 @提及 与附件外链校验:
    • 若希望通过机器人回复唤醒特定负责人,不能在 text.content 里写纯文本 "@张三",而必须在 rich_text 数组中构造 "type": "mention", "mention": {"type": "user", "user": {"id": "<user_uuid>"}} 对象,才能触发对方侧边栏 Inbox 提醒;若评论需附带截图或工单附件,建议先通过文件直传生成受控资产或写入稳定 HTTPS 外链,避免使用临时鉴权 URL 导致几天后裂图。
  5. 警惕页面权限降级或集成被移出授权范围引发的静默失败:
    • 当某个项目页面被团队空间管理员调整为私有或移除了外部集成的 Connections 授权时,GET /v1/comments 会立即返回 404 object_not_found(而非 403)。同步队列应把 404 归类为“授权缺失或页面已进废纸篓”告警并暂停重试,切忌在死信队列里无限空转消耗额度。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。