# User Feedback

Collect user feedback on AI responses, map it to system events, and filter sessions by sentiment.

User feedback is one of the most valuable signals for improving your AI product. Brizz lets you capture thumbs-up/thumbs-down reactions (or any custom feedback), surface them in your session views, and filter by sentiment to quickly find what's working and what isn't.

This guide walks through the full setup: emitting feedback events from your code, mapping them to system events in the dashboard, and using the built-in filters and charts.

## 1. Emitting Feedback Events

Use the SDK to emit events whenever a user provides feedback. There are two common patterns.

### Pattern A: Separate Event Names

Emit distinct events for positive and negative feedback:

:::tabs
:::tab[Python]

```python
from brizz import emit_event

# Positive feedback
emit_event(
    "feedback.positive",
    attributes={
        "category": "helpfulness"       # optional
    },
    body={
        "comment": "This was exactly what I needed!",  # optional
        "context": "billing-assistant"                 # optional
    }
)

# Negative feedback
emit_event(
    "feedback.negative",
    attributes={
        "category": "accuracy"          # optional
    },
    body={
        "comment": "The answer was outdated.",         # optional
        "context": "billing-assistant"                 # optional
    }
)
```

:::tab[Node.js]

```typescript
import { emitEvent } from '@brizz/sdk';

// Positive feedback
emitEvent(
  'feedback.positive',
  {
    category: 'helpfulness', // optional
  },
  {
    comment: 'This was exactly what I needed!', // optional
    context: 'billing-assistant', // optional
  },
);

// Negative feedback
emitEvent(
  'feedback.negative',
  {
    category: 'accuracy', // optional
  },
  {
    comment: 'The answer was outdated.', // optional
    context: 'billing-assistant', // optional
  },
);
```

:::

### Pattern B: Single Event with Sentiment Attribute

Use one event name and differentiate with an attribute:

:::tabs
:::tab[Python]

```python
from brizz import emit_event

emit_event(
    "feedback.submitted",
    attributes={
        "sentiment": "positive",   # or "negative"
        "category": "helpfulness"  # optional
    },
    body={
        "comment": "Great response!",      # optional
        "context": "support-agent"         # optional
    }
)
```

:::tab[Node.js]

```typescript
import { emitEvent } from '@brizz/sdk';

emitEvent(
  'feedback.submitted',
  {
    sentiment: 'positive', // or 'negative'
    category: 'helpfulness', // optional
  },
  {
    comment: 'Great response!', // optional
    context: 'support-agent', // optional
  },
);
```

:::

:::info
**Which pattern should I use?** Pattern A (separate events) is simpler to map in the dashboard — each event maps directly to a system event with no conditions. Pattern B (single event) is more flexible if you plan to add more sentiment types later (e.g., `neutral`), but requires conditional mapping.
:::

## 2. Configuring System Event Mappings

Once your application is emitting feedback events, you need to tell Brizz which of your custom events correspond to the built-in **Positive Feedback** and **Negative Feedback** system events. This enables feedback badges, preset filters, and dashboard charts.

### Opening Event Settings

1. Navigate to **Organization Settings** (gear icon in the sidebar).
2. Select the **Event** tab.

### Simple Mapping (Pattern A)

If you're using separate event names (`feedback.positive` / `feedback.negative`):

1. Find the **Positive Feedback** row in the system events list.
2. Click **Add Mapping**.
3. Select the trace service that emits your events.
4. Choose `feedback.positive` from the source event dropdown.
5. Click **Save**.

![Selecting a source event type for the Positive Feedback system event](event_mapping_multi_events.png)

Repeat for **Negative Feedback**, mapping it to `feedback.negative`.

### Conditional Mapping (Pattern B)

If you're using a single `feedback.submitted` event with a `sentiment` attribute:

1. Find the **Positive Feedback** row and click **Add Mapping**.
2. Select your trace service and choose `feedback.submitted` as the source event.
3. Click **Add Condition**.
4. Set the condition: `sentiment` **equals** `positive`.
5. Click **Save**.

![Maaping event params to system event](event_mapping_single_event_type.png)

Repeat for **Negative Feedback** with the condition `sentiment` **equals** `negative`.

### Multiple Mappings (OR Logic)

You can add more than one mapping to a system event. For example, if different services emit feedback events with different names, map them all to the same system event. Brizz treats multiple mappings as **OR** — any match triggers the system event.

:::info
**Changes take effect immediately.** Once you save a mapping, Brizz will start classifying incoming events. Historical events are not retroactively reclassified.
:::

## 3. Filtering Sessions by Feedback

With mappings configured, Brizz automatically tags sessions that contain feedback events.

### Preset Filters

The Sessions page includes built-in filter presets:

- **Negative Sessions** — Shows only sessions containing at least one negative feedback event.
- **Positive Sessions** — Shows only sessions containing at least one positive feedback event.

![Multiple event mappings configured for a single system event](event_mapping_multi_events.png)

Click a preset chip to apply it instantly.

### Feedback Badges

Sessions that contain feedback events display a badge in the session list:

- A **thumbs-up** icon for sessions with positive feedback.
- A **thumbs-down** icon for sessions with negative feedback.
- If a session has both, both badges appear.

![Session list with feedback badges marking positive and negative sessions](session_mark_with_feedback.png)

### Dashboard Feedback Charts

The Overview dashboard includes a feedback distribution chart showing the ratio of positive to negative feedback over time. Use this to track sentiment trends and measure the impact of improvements.

![Feedback distribution chart on the Overview dashboard](feedback_chart.png)

## Best Practices

1. **Always emit feedback inside a session.** Feedback events are most useful when they're linked to a session, so Brizz can correlate them with the traces and LLM calls that produced the response.
2. **Include a category attribute.** Adding a `category` (e.g., `accuracy`, `helpfulness`, `speed`) lets you break down feedback by dimension later.
3. **Use the body for free-text comments.** Put user comments in the `body` parameter so they're stored but don't clutter your filterable attributes.
4. **Map early.** Configure your event mappings as soon as you start emitting feedback events — mappings only apply to new incoming data.

## See also

- [Record feedback](/docs/instrument/record-feedback.md) — the `record_feedback` / `recordFeedback` helper. It emits a `brizz.feedback` event but does *not* feed the badges, filters, or chart described here — map a system event on this page for that.
- [Custom events](/docs/instrument/custom-events.md) — naming conventions and the attributes/body distinction.
- [Sessions](/docs/instrument/sessions.md) — make sure feedback events are attached to a session.
- [Issues](/docs/platform/issues.md) — sustained negative feedback surfaces here as a quality issue.