# Notion integration (push feedback to a database)

Push feedback items and clusters from Usero into a Notion database you choose. It is a one-way push: Usero creates pages in your
database and reads nothing from your workspace beyond the databases you explicitly share with it. Each pushed item becomes a new
database row with the summary up top, user verbatims in the page body, and a link back to the item in Usero.

Connecting takes about two minutes and uses a Notion internal integration that you create in your own workspace. Usero never sees
your Notion password and you can revoke access at any time by deleting the integration in Notion or disconnecting in Usero.

## What it does

- **Push any feedback item or cluster to Notion.** A "Send to Notion" button on the feedback and cluster detail pages creates a
  new page in your chosen database. After a send, the button becomes a "View in Notion" link.
- **Optional auto-send.** Off by default. When you turn it on, every new feedback item is pushed to Notion as it arrives. Bulk
  imports (CSV, GitHub backfill, app review syncs) are never auto-sent, so a large import cannot flood your database.
- **Schema-aware mapping.** Usero reads your database's properties and fills the ones it recognises. A property your database does
  not have is simply skipped; the page body always carries the full content either way.

## Set up

### 1. Create an internal integration in Notion

1. In Notion, open [Settings, then Connections, then Develop or manage integrations](https://www.notion.so/profile/integrations).
2. Click **New integration**. Give it a name (for example "Usero"), pick the workspace that holds your target database, and keep
   the type as **Internal**.
3. After saving, copy the **Internal Integration Secret** (it starts with `ntn_`).

### 2. Share your database with the integration

Your integration can only see databases you share with it. In Notion, open the target database as a full page, click the **•••**
menu in the top right, choose **Connections**, and add the integration you just created.

### 3. Connect in Usero

1. Open your project, then go to **Integrations** (the URL is `usero.io/YOUR_CLIENT_ID/integrations`). To open your own
   integrations page, [go here](/integrations?integration=notion).
2. Find the **Notion** card, paste the secret, and click **Connect Notion**. Usero verifies the token and shows the databases you
   shared with the integration.
3. Pick the target database and click **Use this database**.
4. Click **Send a test page** to confirm the pipeline. The test page appears in your database within a couple of seconds.

## Property mapping

Usero fills a database property when your schema has a property with a matching name (case does not matter) and a compatible type.
Everything else is skipped without error, and the full content always lands in the page body.

| Your property name  | Property type    | What Usero writes                                          |
| ------------------- | ---------------- | ---------------------------------------------------------- |
| The title property  | Title (any name) | Cluster title, or the feedback summary / truncated comment |
| Status              | Status or Select | Open, Resolved (feedback) or Open, Addressed (clusters)    |
| Votes or Requesters | Number           | The cluster's feedback count                               |
| Source              | URL              | A deep link to the item in your Usero dashboard            |
| Tags                | Multi-select     | The AI category plus topic keywords                        |
| Sentiment           | Select           | Positive, Neutral, or Negative                             |
| Created             | Date             | When the feedback arrived / the cluster was first seen     |

The page body contains the description or AI summary, up to five member verbatims for clusters, and a "View in Usero" link.

## Re-sending

Sending an item that was already pushed creates a new page rather than updating the old one. The button is labelled "Send again
(new page)" so this is never a surprise. If you want a clean database, delete the older page in Notion.

## Limits

- Text values are capped at 2,000 characters per block (a Notion limit). Longer comments are truncated with an ellipsis.
- Cluster pages include at most five member verbatims.
- Notion allows roughly three requests per second per integration. A push is two requests, so rapid-fire sends may briefly hit the
  rate limit; wait a few seconds and retry.

## Troubleshooting

**The database picker is empty.** The integration cannot see any databases yet. Open the target database in Notion, click the
**•••** menu, then **Connections**, and add your integration. Then refresh the picker.

**"Notion rejected the integration token."** The secret is wrong, was regenerated, or the integration was deleted. Copy the
current secret from Notion's integration settings and reconnect.

**"Notion's firewall blocked this request."** Notion's web application firewall sometimes blocks API traffic before it reaches the
API itself. This is a Notion-side block, not a problem with your token or setup. It usually clears on retry; if it keeps
happening, [contact us](/contact?subject=bug).

**A property is not being filled.** Check the mapping table above: the property name must match (for example `Votes`, not
`Vote count`) and the type must be compatible (for example Tags must be a multi-select, not a select). Rename the property in
Notion and re-send.

**Long comments look cut off.** Notion caps text blocks at 2,000 characters. The full text is always available via the "View in
Usero" link on the page.