Notion

Create a new bot

Scaffold a Next.js bot with the Notion adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

import { Chat } from "chat";
import { createNotionAdapter } from "@chat-adapter/notion";
import { createRedisState } from "@chat-adapter/state-redis";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    notion: createNotionAdapter(),
  },
  state: createRedisState(),
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Notion!");
});

import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.notion(request, {
    waitUntil: (task) => after(() => task),
  });
}

Platform setup

The adapter targets a single workspace through an access-token connection.

Authentication

Vercel Connect

Use Vercel Connect for the outbound Notion access token:

import { createNotionAdapter } from "@chat-adapter/notion";
import { connectNotionAdapter } from "@vercel/connect/chat";

const notion = createNotionAdapter({
  ...connectNotionAdapter("notion/acme-notion"),
  verificationToken: process.env.NOTION_VERIFICATION_TOKEN,
});

Create the connector and attach it to your project with the Vercel CLI. Notion webhooks go directly to your app, so omit --triggers. vercel env pull downloads a development OIDC token for local runs:

vercel link
vercel connect create notion --name acme-notion
vercel connect attach notion/acme-notion
vercel env pull

Access token

Set NOTION_TOKEN to the access token you copied in Platform setup, or pass it as token.

Configuration

token and verificationToken are required at runtime, from the environment or config.

Environment variables

Webhooks

You create subscriptions on the connection's Webhooks tab, not through the API.

1. Deploy your app so https://your-domain.com/api/webhooks/notion is publicly reachable.
2. On the connection page, open the Webhooks tab and click Create a subscription.
3. Set the Webhook URL, leave the default API version as it is, and under Events deselect every category except Comment. This selects Comment created, Comment deleted, and Comment updated. The adapter requires Comment created; the base adapter acknowledges and ignores deleted and updated events.
4. Notion sends a one-time POST containing verification_token. The adapter logs it at warn level and returns 200.
5. Paste that token into Notion's UI and click Verify.
6. Set the same value as NOTION_VERIFICATION_TOKEN (or pass verificationToken in config), then restart so signed deliveries can be verified.

After verification, the adapter checks every delivery with HMAC-SHA256 over the raw body against X-Notion-Signature (sha256=<hex>).

Event-ID deduplication is best-effort: in memory, plus state-backed when a Chat state adapter is configured. It does not substitute for Notion's delivery semantics across cold starts unless the state adapter is durable.

Mention detection

createNotionAdapter({
  userName: "docs-bot",
  // default mentionMode: "mention" → triggers on "@docs-bot" or "@<bot-user-id>"
});

createNotionAdapter({
  mentionMode: "keyword",
  keywords: ["@docs-bot", "hey bot"],
});

Streaming and rate limits

Notion allows a connection to update its own comments, so the adapter uses Post+Edit streaming: it posts the first chunk, then PATCHes the same comment as tokens arrive.

Notion's average rate limit is about 3 requests per second per connection, plus shared workspace limits. The adapter:

• Throttles streaming edits with a default minimum interval of 1500ms (streamingEditIntervalMs)
• Always flushes a final edit
• Applies a shared limiter to all API calls and honors Retry-After on HTTP 429

Override the interval per stream with updateIntervalMs on the stream options.

Message history

fetchMessages uses Notion's list-comments API (GET /v1/comments?block_id={pageId}), paginated ascending, then filters client-side to the requested discussion_id. The adapter assumes list-comments returns oldest first, because Notion does not document the order. With the SDK default direction: "backward", you get the newest page of matching discussion comments from that assumed order.

Message subject

await message.subject resolves the parent Notion page (GET /v1/pages/{pageId}) on first access and caches the result.

The subject is the Notion page object from the Pages API (title, properties, URL, and the full payload on raw), not the page's block children or body content (GET /v1/blocks/.../children). See Message Subject.

Cards and files

Notion has no native card UI. JSX cards render as markdown through fallbackText or flattened content, the same pattern as Linear and GitHub. Interactive buttons and callbackUrl are unsupported.

Outbound files use Notion's File Uploads API and attach up to 3 files as native comment attachments:

• Binary uploads use single_part, up to Notion's single-part limit of about 20 MiB.
• Public URLs use external_url and are polled until uploaded before attaching. By default the adapter rechecks immediately, then after 5s and 10s; configure this with externalUrlPollDelaysMs.
• Files beyond the first 3, uploads still pending after the poll window, and other upload failures fall back to markdown links in the comment body. Edits link files in markdown only.

API version

Every request sends:

Notion-Version: 2026-03-11

That pin is exported as DEFAULT_NOTION_VERSION from @chat-adapter/notion. Override it with notionVersion or NOTION_VERSION only if you accept the risk of breakage when Notion's versioned API diverges.

Thread model

One Notion page is one Chat SDK channel, and each discussion is a thread.

Inbound comment.created events always include a discussion_id. The adapter resolves the containing page, including for block-parent comments, and dispatches on notion:{pageId}:{discussionId} so replies stay threaded.

Comment edits and deletions require Read comments to retrieve the target before writing. The adapter throws a ValidationError if the comment is missing or belongs to another page, discussion, or block than the supplied thread ID. For block-parent comments, it retrieves the current block ancestry rather than relying on cached page ownership.

Posts also throw a ValidationError when the thread ID points at another page, and the check runs before any file is uploaded or comment is sent. A whole-block thread ID must name a block on its page, which the adapter confirms from the current block ancestry. Child page and child database blocks are rejected. A discussion thread ID must name a discussion the adapter has recorded for that page. It records a discussion when a comment.created webhook arrives for it, when the bot starts it, or when it finds the discussion in the page's comment list, and keeps the record in the state adapter so every instance shares it. The comment list only covers unresolved, page-level discussions. A post to any other discussion with no record, such as an inline or block discussion whose thread ID was saved before this check existed, throws until a new comment in that discussion arrives through the webhook.

Use getPageUrl to build deep links:

const notion = bot.getAdapter("notion");
const url = notion.getPageUrl(thread.id); // includes ?d={discussionId} when present

Feature support