Feedback

Collecting qualitative user input with optional attachments, replay links, and error associations.

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in RFC 2119 to indicate requirement levels.

Statusstable

Version1.3.0(changelog)

User feedback allows Sentry to collect qualitative input directly from users — free-form comments describing what happened, optionally accompanied by contact information, linked errors, replay recordings, and file attachments. An SDK sends feedback as a feedback envelope item containing an event payload with a feedback context object.

Related specs:

Envelopes — transport format
Event Payloads — base event attributes
User Report (Deprecated) — deprecated predecessor

A feedback event is an event payload with a feedback context object. The feedback context carries user-provided data (message, contact info, URLs), while the event payload carries standard attributes (timestamp, event_id, platform, user, tags, etc.).

Files of any type (screenshots, logs, documents) can accompany a feedback event by sending them as attachment items in the same envelope. Sentry uses the shared event_id to associate attachments with the feedback.

Stablespecified since 1.0.0

A feedback captured by capture_feedback is processed through the SDK pipeline. The feedback event can be discarded at any stage, at which point no further processing happens.

SDKs SHOULD implement a beforeSendFeedback callback to allow users to modify or discard the feedback before it is sent. This callback SHOULD be similar to the existing beforeSend callback used for error events. Feedback events MUST NOT go through the beforeSend hook.

SDKs MUST apply scope data to the feedback event, including tags, user, trace, and contexts. The scope's event processors MUST also be invoked.

SDKs MUST apply rate limiting to feedbacks in the same way as it is applied to events.

There is no sample rate for feedbacks — they are always sent. However, a feedback can be discarded at any pipeline stage (rate limiting, invalid message, etc.). SDKs SHOULD report dropped feedbacks through client reports.

Stablespecified since 1.0.0

When sending feedback, SDKs SHOULD flush the current Session Replay, if running. This ensures a meaningful replay recording exists and can be included in the replay_id attribute of the feedback context.

Stablespecified since 1.1.0

For feedback widgets specifically, when Session Replay's onErrorSampleRate is greater than 0, SDKs MUST sample and flush the replay when the widget opens, not when the user submits the feedback.

This timing is critical because:

The replay buffer captures the user's session leading up to opening the feedback widget, providing context about what the user experienced before deciding to provide feedback.
If sampling only occurs on submission, the buffer would primarily contain the user's interactions with the feedback form itself, which provides minimal debugging value.
Early sampling ensures the complete user context is preserved regardless of whether the user ultimately submits the feedback.

Stablespecified since 1.2.0

When feedback is captured using the manual API (capture_feedback), SDKs MUST sample and flush the replay during the execution of the feedback capture API to ensure session context is preserved.

Stablespecified since 1.0.0

On user-facing platforms such as mobile, desktop, or browser, SDKs SHOULD provide first-class support for requesting user feedback when an error or crash occurs. See the user-facing docs for Apple and Java for API examples.

On mobile and desktop, it is common to prompt the user for feedback after a crash happened on the previous run of the application. SDKs SHOULD implement the onCrashedLastRun callback on the options. This callback gets called shortly after the initialization of the SDK when the last program execution terminated with a crash. The SDK SHOULD execute the callback only once during the entire run of the program to avoid multiple callbacks if there are multiple crash events to send.

Stablespecified since 1.0.0

On backend platforms, SDKs SHOULD document how to use the last event ID to prompt the user for feedback themselves.

Stablespecified since 1.0.0

A feedback is sent as a feedback envelope item containing a JSON object. The object is an event payload with an additional feedback context object.

This Item MAY occur at most once per Envelope.
This Item is mutually exclusive with "transaction" items.

event_id: UUID String, required. Corresponds to the event_id field of the event payload. It is not equal to the associated_event_id field in the feedback context. Clients are required to generate an event identifier ahead of time and set it at least in the Envelope headers. If the identifier mismatches between the Envelope and payload, the Envelope header takes precedence.

None

Below is a recap of the required attributes for the event payload. For the full list of attributes, see Event Payloads.

Field	Type	Required	Since	Description
`event_id`	String	REQUIRED	1.0.0	Hexadecimal string representing a UUID v4 value.
`timestamp`	Number	REQUIRED	1.0.0	UNIX timestamp of the current time (in seconds).
`platform`	String	REQUIRED	1.0.0	Platform of the SDK.

The contexts.feedback object carries user-provided feedback data:

Field	Type	Required	Since	Description
`message`	String	REQUIRED	1.0.0	Comments of the user, describing what happened and/or sharing feedback. Max length: 4096 characters.
`contact_email`	String	OPTIONAL	1.0.0	Email of the user who submitted the feedback. If excluded, Sentry (not the SDK) attempts to fill this in from user context. Anonymous feedbacks (no name or email) are accepted.
`name`	String	OPTIONAL	1.0.0	Name of the user who submitted the feedback. If excluded, Sentry (not the SDK) attempts to fill this in from user context.
`url`	String	OPTIONAL	1.0.0	URL of the webpage the user was on when submitting feedback. May be used for search or alerts.
`associated_event_id`	String	OPTIONAL	1.0.0	Identifier of an error event in the same project. Links a related error in the feedback UI.
`replay_id`	String	OPTIONAL	1.0.0	Identifier of a related Session Replay in the same project. Sentry uses this to render a Replay clip in the feedback UI.

Stablespecified since 1.0.0

SDKs MAY attach files of any type to a feedback (screenshots, logs, documents, etc.) by sending them as attachment items, with event_id corresponding to the feedback item. SDKs SHOULD send attachment items in the same envelope as the feedback item. (since 1.3.0) Attachments are not limited to screenshots — any file type is supported.

Stablespecified since 1.0.0

SDKs MUST expose a top-level function to send a feedback:

Copied

captureFeedback(feedback) -> eventId

captureFeedback(feedback) -> eventId

Parameters:

feedback — Object containing at minimum message. Optionally includes contact_email, name, url, associated_event_id, and replay_id.

Returns: The eventId (string).

Naming SHOULD follow the SDK's language conventions:

captureFeedback (JavaScript, Java)
capture_feedback (Python, Ruby)
CaptureFeedback (Go, .NET)

Copied

{
  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
  "timestamp": "2011-05-02T17:41:36Z",
  "platform": "javascript",
  "contexts": {
    "feedback": {
      "contact_email": "john@example.com",
      "name": "John Smith",
      "message": "I love session replay!",
      "url": "https://sentry.io/replays/",
      "associated_event_id": "32fd1995636d446385016e2747623e11",
      "replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
    }
  }
}

{
  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
  "timestamp": "2011-05-02T17:41:36Z",
  "platform": "javascript",
  "contexts": {
    "feedback": {
      "contact_email": "john@example.com",
      "name": "John Smith",
      "message": "I love session replay!",
      "url": "https://sentry.io/replays/",
      "associated_event_id": "32fd1995636d446385016e2747623e11",
      "replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
    }
  }
}

Copied

{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","sent_at":"2024-03-19T15:18:27.581Z","sdk":{"name":"sentry.javascript.react","version":"7.105.0"}}
{"type":"feedback"}
{
  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
  "timestamp": "2011-05-02T17:41:36Z",
  "platform": "javascript",
  "contexts": {
    "organization": { "id": "0", "slug": "sentry" },
    "feedback": {
      "contact_email": "john@example.com",
      "name": "John Smith",
      "message": "I love session replay!",
      "url": "https://sentry.io/replays/",
      "associated_event_id": "32fd1995636d446385016e2747623e11",
      "replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
    }
  },
  "level": "error",
  "environment": "prod",
  "release": "frontend@f00",
  "sdk": {
    "integrations": [
      "BrowserTracing",
      "BrowserProfiling",
      "Replay",
      "ReplayCanvas"
    ],
    "name": "sentry.javascript.react",
    "version": "7.105.0"
  },
  "tags": {
    "sentry_version": "24.4.0.dev0"
  },
  "user": {
    "ip_address": "127.0.0.1",
    "email": "john@example.com",
    "id": 1,
    "name": "John Smith"
  }
}
{"type":"attachment","length":1234,"filename":"screenshot.png"}
<binary screenshot data>
{"type":"attachment","length":567,"filename":"debug-logs.txt"}
<text file content>

{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","sent_at":"2024-03-19T15:18:27.581Z","sdk":{"name":"sentry.javascript.react","version":"7.105.0"}}
{"type":"feedback"}
{
  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
  "timestamp": "2011-05-02T17:41:36Z",
  "platform": "javascript",
  "contexts": {
    "organization": { "id": "0", "slug": "sentry" },
    "feedback": {
      "contact_email": "john@example.com",
      "name": "John Smith",
      "message": "I love session replay!",
      "url": "https://sentry.io/replays/",
      "associated_event_id": "32fd1995636d446385016e2747623e11",
      "replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
    }
  },
  "level": "error",
  "environment": "prod",
  "release": "frontend@f00",
  "sdk": {
    "integrations": [
      "BrowserTracing",
      "BrowserProfiling",
      "Replay",
      "ReplayCanvas"
    ],
    "name": "sentry.javascript.react",
    "version": "7.105.0"
  },
  "tags": {
    "sentry_version": "24.4.0.dev0"
  },
  "user": {
    "ip_address": "127.0.0.1",
    "email": "john@example.com",
    "id": 1,
    "name": "John Smith"
  }
}
{"type":"attachment","length":1234,"filename":"screenshot.png"}
<binary screenshot data>
{"type":"attachment","length":567,"filename":"debug-logs.txt"}
<text file content>

User Feedback class:

Envelope item:

Version	Date	Summary
`1.3.0`	2026-02-04	Broadened attachments from screenshots-only to any file type, added attachment examples to envelope
`1.2.0`	2025-06-30	Added manual API replay sampling timing requirement
`1.1.0`	2025-06-19	Added replay sampling timing requirement for feedback widgets
`1.0.0`	2025-04-15	Initial spec — feedback protocol, envelope item constraints, context attributes, SDK pipeline, session replay integration, platform-specific guidance (onCrashedLastRun, user-facing/backend platforms)

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support