feat(feedback): document new feedback envelope format and rename old format (#12188)

* feat(feedback): document new feedback envelope format and rename old format

* Attachments note

* Doc max message length

* Review comments - rewording and rm max screenshots

Author: aliu39

develop-docs/application-architecture/feedback-architecture.mdx

@@ -11,17 +11,17 @@ It will:
 
 ## Creation sources
 
-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
+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
 `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](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples) created by the Replay team when adding
+`NEW_FEEDBACK_ENVELOPE`: [The new format](/sdk/data-model/envelope-items/#user-feedback) 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](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback) with name/email/comments, that requires
+`USER_REPORT_ENVELOPE`: [The older format](/sdk/data-model/envelope-items/#user-report) 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](https://develop.sentry.dev/issue-platform/).
+saved via the [issues platform](/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 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 preferred way of sending feedback from the SDK is in [feedback envelope](/sdk/data-model/envelope-items/#user-feedback).
 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](https://develop.sentry.dev/sdk/data-model/envelopes/#attachment)
+to submit **at most 1 screenshot per feedback**. Attachments are another [item type](/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,9 +186,7 @@ graph TD
 
 ### Envelopes
 
-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"`.**
+User reports are also sent to Relay in envelope format, item type [user_report](/sdk/data-model/envelope-items/#user-report).
 
 The SDK function that sends these is `captureUserFeedback`.
 

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
+Item type `"event"`. This Item contains an error or default [event payload](/sdk/data-model/event-payloads/)
 encoded in JSON.
 
 **Constraints:**
@@ -181,18 +181,101 @@ details.
 
 ### User Feedback
 
-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:
+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","email":"[email protected]","name":"John Me","comments":"It broke."}\n
+{
+  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
+  "timestamp": "2011-05-02T17:41:36Z",
+  "platform": "javascript",
+  "level": "error",
+  "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"
+    }
+  }
+}
 ```
 
-**Attributes**
+**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.** The identifier of the event or transaction.
+: **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:
+```json
+{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"[email protected]","name":"John Me","comments":"It broke."}\n
+```
+
+**Payload Attributes**
+
+`event_id`
+
+: **UUID String, required.** The identifier of the associated event, ideally
+an error.
 
 `email`
 
@@ -204,19 +287,25 @@ The item contains a user feedback / user report JSON payload:
 
 `comments`
 
-: *String, recommended.* Comments of the user about what happened.
+: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**.
 
 **Constraints:**
 
 - This Item may occur once per Envelope.
-- User Feedbacks / Reports can be ingested separately from their events. We recommended to
-  send them in the same 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.
 
 **Envelope Headers:**
 
 `event_id`
 
-: **UUID String, required.** The identifier of the event or transaction.
+: **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.
 
 **Additional Item Headers:**
 

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-feedback). 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-report). 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