@chat-adapter/notion
npm package:
@chat-adapter/notion
Notion adapter for Chat SDK. Participate in page and block comment discussions via Notion webhooks and the Comments API.
Documentation: chat-sdk.dev/adapters/official/notion · Guides: vercel.com/kb/chat-sdk
Installation
pnpm add @chat-adapter/notion
Scaffold with the CLI
To scaffold a new Notion bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter notion memory
Visit the adapters directory to see other available official and vendor-official adapters.
Quick start
For managed credentials, see Vercel Connect.
The adapter auto-detects credentials from NOTION_TOKEN, NOTION_VERIFICATION_TOKEN, and optional NOTION_BOT_USERNAME / NOTION_VERSION / NOTION_MENTION_MODE / NOTION_KEYWORDS:
import { Chat } from "chat";
import { createNotionAdapter } from "@chat-adapter/notion";
const bot = new Chat({
userName: "my-bot",
adapters: {
notion: createNotionAdapter(),
},
});
bot.onNewMention(async (thread, message) => {
await thread.post("Hello from Notion!");
});
Configuration
| Option | Description |
|---|---|
token | Notion access token or async resolver. Auto-detected from NOTION_TOKEN. |
verificationToken | Native webhook verification token. Auto-detected from NOTION_VERIFICATION_TOKEN. |
Both are required. See the full configuration reference for mention detection and other options.
Vercel Connect
Use connectNotionAdapter to resolve the outbound Notion access token from
Vercel Connect:
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,
});
Connect does not forward Notion webhooks. Configure the webhook subscription
directly in Notion and keep NOTION_VERIFICATION_TOKEN for native HMAC
verification. NOTION_TOKEN is not needed when using the Connect helper.
AI Coding Agents
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chat
The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
License
MIT