getsentry · aliu39 · Jan 6, 2025 · Jan 6, 2025
diff --git a/develop-docs/application-architecture/feedback-architecture.mdx b/develop-docs/application-architecture/feedback-architecture.mdx
@@ -11,17 +11,17 @@ It will:
 
 ## Creation sources
 
-When broken down, there are **4** ways to create feedback in our system, with
-3 sharing the same data model. A good reference is the
+When broken down, there are **5** ways to create feedback in our system 😵‍💫.
+(But 4 of them, related to user reports, are quite similar!) A good reference is the
 `FeedbackCreationSource(Enum)` in [create_feedback.py](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L33-L33).
 The 4 ways _clients_ can create feedback are:
 
-`NEW_FEEDBACK_ENVELOPE`: [The new format](/sdk/data-model/envelope-items/#user-feedback) created by the Replay team when adding
+`NEW_FEEDBACK_ENVELOPE`: [The new format](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples) created by the Replay team when adding
 the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget)
 to the JavaScript SDK. It allows adding more information, for example tags,
 release, url, etc.
 
-`USER_REPORT_ENVELOPE`: [The older format](/sdk/data-model/envelope-items/#user-report) with name/email/comments, that requires
+`USER_REPORT_ENVELOPE`: [The older format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback) with name/email/comments, that requires
 `event_id` to link a Sentry error event.
 
 `USER_REPORT_DJANGO_ENDPOINT`: [The deprecated Web API](https://docs.sentry.io/api/projects/submit-user-feedback/)
@@ -31,7 +31,7 @@ release, url, etc.
 ## How feedback is stored
 
 On the backend, each feedback submission in Sentry's UI is **an un-grouped issue occurrence**,
-saved via the [issues platform](/issue-platform/).
+saved via the [issues platform](https://develop.sentry.dev/issue-platform/).
 The entrypoint is [**`create_feedback_issue()`**](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L184-L184),
 which
 
@@ -42,7 +42,7 @@ which
 
 ## Feedback events
 
-The preferred way of sending feedback from the SDK is in [feedback envelope](/sdk/data-model/envelope-items/#user-feedback).
+The new and preferred way to send feedback from the SDK is in an [event envelope](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples).
 The format is the same as error events, except the `type` header = `"feedback"`. While
 user reports have an associated event, **new feedback _is_ an event**. This
 offers 2 improvements:
@@ -94,7 +94,7 @@ In Relay v24.5.1, we migrated feedback to its own kafka topic + consumer,
 ### Attachments
 
 We only use attachments for the widget’s screenshot feature, which allows users
-to submit **at most 1 screenshot per feedback**. Attachments are another [item type](/sdk/data-model/envelopes/#attachment)
+to submit **at most 1 screenshot per feedback**. Attachments are another [item type](https://develop.sentry.dev/sdk/data-model/envelopes/#attachment)
 in an envelope.
 
 - SDK v8.0.0+, Relay v24.5.1+: Sends the feedback and attachment items in the same envelope.
@@ -186,7 +186,9 @@ graph TD
 
 ### Envelopes
 
-User reports are also sent to Relay in envelope format, item type [user_report](/sdk/data-model/envelope-items/#user-report).
+User reports are also sent to Relay in [envelope format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback).
+**This item type is misleadingly called “user feedback” in some of our docs, but the
+item header will read `"user_report"`.**
 
 The SDK function that sends these is `captureUserFeedback`.
 

diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx
@@ -16,7 +16,7 @@ The headers described in this section are **in addition to the common headers**.
 
 ### Event
 
-Item type `"event"`. This Item contains an error or default [event payload](/sdk/data-model/event-payloads/)
+Item type `"event"`. This Item contains an error or default event payload
 encoded in JSON.
 
 **Constraints:**
@@ -181,101 +181,18 @@ details.
 
 ### User Feedback
 
-Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/event-payloads/) encoded in JSON, with an additional `feedback` context object.
-
-Example payload:
-```json
-{
-  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
-  "timestamp": "2011-05-02T17:41:36Z",
-  "platform": "javascript",
-  "level": "error",
-  "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"
-    }
-  }
-}
-```
-
-**Payload Attributes**
-
-We only document attributes for the `contexts.feedback` object, which is **required**
-for this item type. For other attributes, see [Event Payloads](/sdk/data-model/event-payloads/).
-
-`message`
-
-: **String, required.** Comments of the user, describing what happened and/or sharing
-feedback. The max length is **4096 characters**.
-
-`contact_email`
-
-: *String, recommended.* The email of the user who submitted the feedback.
-
-`name`
-
-: *String, optional.* The name of the user who submitted the feedback.
-
-`url`
-
-: *String, optional.* The URL of the webpage the user was on when submitting feedback.
-  This may be used to search for or set alerts on feedback.
-
-`associated_event_id`
-
-: *UUID String, optional.* The identifier of an error event in the same project.
-  Use this to explicitly link a related error in the feedback UI.
-
-`replay_id`
-
-: *UUID String, optional.* The identifier of a related Session Replay in the same
-  project. Sentry uses this ID to render a Replay clip in the feedback UI.
-
-**Attaching Screenshots:**
-
-You can associate screenshots with a feedback by sending image data as
-[attachment items](/sdk/data-model/envelope-items/#attachment), with `event_id`
-corresponding to the feedback item. We recommend sending the items in the same
-Envelope.
-
-**Constraints:**
-
-- This Item may occur at most once per Envelope.
-- This Item is mutually exclusive with `"transaction"` items.
-
-**Required Envelope Headers:**
-
-`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.
-
-### User Report
-
-Item type `"user_report"`. This is an older way of submitting user feedback we
-are in the process of deprecating. It works by associating user information and
-comments with an event. If both the item and its associated event are accepted,
-we convert it to a user feedback.
-
-The item contains a JSON payload like this:
+User Feedback was called User Report in the beginning. Therefore the envelope item type is `"user_report"`.
+The item contains a user feedback / user report JSON payload:
 ```json
 {"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@me.com","name":"John Me","comments":"It broke."}\n
 ```
 
-**Payload Attributes**
+**Attributes**
 
 `event_id`
 
-: **UUID String, required.** The identifier of the associated event, ideally
-an error.
+: **UUID String, required.** The identifier of the event or transaction.
+
 
 `email`
 
@@ -287,25 +204,19 @@ an error.
 
 `comments`
 
-: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**.
+: *String, recommended.* Comments of the user about what happened.
 
 **Constraints:**
 
 - This Item may occur once per Envelope.
-- User Reports can be ingested separately from their events. However, we recommend
-  sending them in the same Envelope.
-- You may not associate multiple User Reports to the same event.
-- The event can not be more than 30 minutes old.
-- If the event does not exist in the same project or was never ingested, the report
-  is discarded and never converted to feedback.
+- User Feedbacks / Reports can be ingested separately from their events. We recommended to
+  send them in the same Envelope.
 
 **Envelope Headers:**
 
 `event_id`
 
-: **UUID String, required.** Corresponds to the `event_id` field of the payload.
-  If the identifier mismatches between the Envelope and payload, the Envelope
-  header takes precedence.
+: **UUID String, required.** The identifier of the event or transaction.
 
 **Additional Item Headers:**
 

diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx
@@ -147,7 +147,7 @@ Ability to get the ID of the last event sent. Event IDs are useful for correlati
 
 ## User Feedback
 
-For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-report). Alternatively, the SDKs can
+For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-feedback). Alternatively, the SDKs can
 use the [User Feedback endpoint](https://docs.sentry.io/api/projects/submit-user-feedback/), which is not recommended.
 
 ### User Facing Platforms