What the Notion integration does

Each new comment on a project that syncs becomes a page in a Notion database you choose, with the screenshot, the page it was left on, and the browser details. The page's status follows the comment, and a status change made in Notion comes back to the comment. For an overview, see the Notion integration page.

Before you start

Plan — Notion is on the Team plan. See Understanding plans and pricing.
Role — only workspace owners and admins can connect Notion and change its settings. Other members can open Integrations and see that Notion is connected.
A database — Huddlekit writes pages into a database you already have. It never creates one. If you want status to sync, the database needs a Status or Select property.

Connect Notion

Open Integrations in your workspace sidebar.
Under Apps, click Connect next to Notion.
On Notion's screen, select the databases Huddlekit may write to, then allow access. Notion has no separate permissions to choose: Huddlekit can see only what you share with it, here or later in Notion.
You're returned to Huddlekit with Notion connected. Nothing syncs until you choose a database, which is the next step.

If you selected no databases, the message reads Notion connected, but no database. See Troubleshooting.

Choose where comments go

Click the ⋯ button on the Notion row and choose Configure. Every change saves as soon as you make it.

Default database — used for every project that isn't set individually, including projects created later. Choose No default if only the projects you pick should sync.
Projects — each website, web app and media project can follow the default, go to a database of its own, or, when there is a default, be set to Don't sync to keep it out of Notion.

Changing a project's database only affects new comments. Pages already created stay where they are and keep their status in sync, even if you later set their project to Don't sync.

When a database is the default, or receives comments from more than one project, each page title starts with the project name in brackets, because comment numbers restart in every project.

Set up status sync

Status syncs through one property on the database: a Notion Status property or a Select property. Click the gear button next to a project, or next to the default database, to open Status mapping for that database. A database's map is shared by every project that sends comments to it, and the dialog says how many that is.

The status property

When you first choose a database, Huddlekit looks for its status column:

A Status property is chosen when there's only one, or only one named Status or State.
A Select property is considered only when the database has no Status property. It's chosen when it's the only Select named Status or State, or the only one with options matching at least two different Huddlekit statuses, such as To do and Done.

Otherwise nothing is chosen, so a column like Type or Priority is never used by mistake. Choosing the same database again later keeps the earlier choice.

You can change it under Status property, or choose No status sync to create pages without touching their status. The database then stays marked with a warning, because its statuses aren't mapped. Changing the property resets that database's mappings to the defaults.

If a database has no status property, pages are still created but their status never syncs. The dialog explains this, and asks you to add a Status or Select property in Notion or pick an existing one.

Mapping statuses

Each Huddlekit status (Open, In review, In progress, Resolved) maps to one option in the property. The defaults work like this:

An option named for a status is used first. For example, "Review" or "In review" for In review, and "Done" or "Complete" for Resolved.
On a Status property, anything still unmapped takes the first option in Notion's matching group: To-do for Open, In progress for In progress, and Complete for Resolved.
In review is mapped by default only when the database has an option named for it.
A Select property has no groups, so any status without an option named for it starts unmapped.

An unmapped status shows Not mapped, and a warning appears next to every project that uses the database. Choosing Never sync this status leaves a status out on purpose, but it still shows Not mapped and the warning stays. A comment moved to a status that isn't mapped doesn't change its page, and a page moved to an option that isn't mapped doesn't change its comment.

What each page contains

Title — the comment number and its first line, for example #42 — The logo overlaps the menu. The first line is cut at 80 characters, and the number and any project name go in front of it.
The full comment text.
The project it belongs to, who reported it, and where it was left. On a website that's a link to the page, on a web app the page's title or path, and on a media file the page number or the time in the video.
The screenshot, except on media files. A screenshot that finishes after the page is created isn't added.
An Environment toggle with the OS, browser, resolution, viewport, pixel ratio, color depth and network, whichever were captured. Media comments have none.
An Open in Huddlekit link back to the comment. For a web app comment it opens the page in your own app where the comment was left.

Private comments are sent too.

What syncs and what doesn't

Status syncs both ways. Change a comment's status and the page's property follows. Change the property in Notion and the comment follows.
The page body is written once, when the comment arrives. Later edits to the comment's text aren't sent, and edits you make to the page in Notion stay in Notion.
Replies, priority, tags, assignees and attachments stay in Huddlekit.
Deleting a comment in Huddlekit doesn't delete its page.
Comments left before you connected, before their project had a database, or while syncing was paused aren't copied in. If one of them changes status later, it gets a page then, as long as its project has a database.
A nightly check picks up status changes made in Notion that didn't come through at the time, as long as the comment hasn't changed in Huddlekit since. If it has, both are left alone, and the page catches up the next time the comment's status changes.

Disconnecting

Click the ⋯ button on the Notion row and choose Disconnect. New comments stop going to Notion, and the pages already created stay in your database.

Notion doesn't let an app remove its own access, so the Disconnected from Notion message stays until you close it and names the last step: "To finish, remove Huddlekit in Notion under Settings, Connections."

If you later reconnect the same Notion workspace, Huddlekit recognizes the pages it already created, so comments aren't duplicated, and your databases and status mappings are kept. Connecting a different Notion workspace starts fresh.

If the workspace leaves the Team plan

If the workspace moves off the Team plan, or a payment is past due, Notion syncing pauses and the row shows Paused. Disconnect stays available on every plan.

Comments and status changes made in Huddlekit while it's paused aren't sent later. Once the workspace is back on an active Team plan, a comment gets its page, or its page catches up, the next time its status changes, if its project has a database by then. Status changes made in Notion during the pause are picked up by the nightly check, unless the comment's status also changed in Huddlekit.

Troubleshooting

"Notion connected, but no database"

No database was selected on Notion's screen. Share the database with Huddlekit in Notion, or choose Reconnect in the ⋯ menu and select it on Notion's screen. The same fix applies when a database you expect isn't in the list: Huddlekit only sees databases you've shared with it.

"Could not read that database from Notion. Make sure it is shared with Huddlekit."

Huddlekit checks a database when you choose it. Share it with Huddlekit in Notion, or reconnect and select it, then choose it again.

A database "no longer exists in Notion, or is no longer shared with Huddlekit"

The database was deleted, or Huddlekit's access to it was removed. Share it again, or point its projects at another database.

"Notion refused the connection. Reconnect Notion."

Huddlekit's access was removed in Notion. Choose Reconnect in the ⋯ menu.

The row says "Not configured"

No project has a database yet, and there's no default. Open Configure and choose one.

A status isn't syncing

A warning icon next to a project means its database has statuses that aren't mapped, or has no status property. Click the icon to open the status mapping and fix it.

The row says "Sync failing"

A comment couldn't be sent to Notion and won't be retried. Open Configure from the ⋯ menu and hover over Sync failing at the top of the dialog for the reason, such as "Notion no longer accepts Huddlekit. Reconnect Notion." It clears once a comment syncs to Notion again.

"Notion not connected"

Connecting didn't finish. The message underneath says why:

Cancelled. Nothing changed. — you cancelled on Notion's screen. Click Connect again when you're ready.
Could not read your databases. Share one with Huddlekit. — Notion didn't respond when Huddlekit asked for the databases you shared. Click Connect again.
That link expired. Start again. — more than ten minutes passed on Notion's screen. Click Connect again.
You switched accounts partway. Sign back in and retry. — you were signed in to Huddlekit as someone else by the time you came back. Sign in as the admin who started, then connect again.
That link was already used. Start again. or That link was not valid. Start again. — click Connect again from Integrations.
Only workspace admins can do this. or Needs the Team plan. — ask an owner or admin, or upgrade the workspace first.
Anything ending in Try again. — click Connect again.

For other tools, see Connecting Linear, Connecting ClickUp and Connecting Slack.

Connecting Notion