Feedback
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
- Envelope Items —
feedbackitem type constraints - Event Payloads — base event attributes
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.
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.
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.
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.
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.
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. |
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.2.0) Attachments are not limited to screenshots — any file type is supported.
SDKs MUST expose a top-level function to send a feedback:
captureFeedback(feedback) -> eventId
Parameters:
feedback— Object containing at minimummessage. Optionally includescontact_email,name,url,associated_event_id, andreplay_id.
Returns: The eventId (string).
Naming SHOULD follow the SDK's language conventions:
captureFeedback(JavaScript, Java)capture_feedback(Python, Ruby)CaptureFeedback(Go, .NET)
{
"event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
"timestamp": "2011-05-02T17:41:36Z",
"platform": "javascript",
"contexts": {
"feedback": {
"contact_email": "[email protected]",
"name": "John Smith",
"message": "I love session replay!",
"url": "https://sentry.io/replays/",
"associated_event_id": "32fd1995636d446385016e2747623e11",
"replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
}
}
}
{"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": "[email protected]",
"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": "[email protected]",
"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>
| Version | Date | Summary |
|---|---|---|
1.2.0 | 2026-02-04 | Broadened attachments from screenshots-only to any file type, added attachment examples to envelope |
1.1.0 | 2025-06-19 | Added replay sampling timing requirement for feedback widgets |
1.0.0 | 2025-04-15 | Initial spec — feedback protocol, context attributes, SDK pipeline, session replay integration |
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").