Collect message feedback
Section ID: Guide/jcpe8h6c8i#collect-message-feedback
Let users say whether an assistant reply helped, with a thumbs-up/down or a 1–10 rating and optional explanation. Each rating belongs to a specific message and rater and is stored with the conversation. Use a completed assistant reply for this control. See message rating and analytics projection for eligibility and when the saved rating appears in analytics.
Save the user’s judgment beside the reply
Section ID: Guide/jcpe8h6c8i#rate-a-message
Build the thumbs-up/down control beside a completed assistant reply. Load the conversation’s existing ratings, render the current user’s choice, then send their change for that message’s sequence. Allow an optional explanation, especially when the reply did not help.
-
Keep the conversation key and assistant message sequence with the rendered reply.
-
Authenticate the rater; do not let the client supply another person as the author.
-
Submit the selected rating below and render the returned stored result.
-
On a lost response, reload the conversation’s ratings before sending another change.
-
Let the user withdraw the rating and show the stored state again.
A rating saved on the message is the immediate result. Its evaluation copy can arrive later, so analytics delay must not make the conversation’s saved rating disappear.
Messages are addressed by their per-conversation messageSequence, not by an ID.
Request example: Rate an assistant message. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Response:
Response example: Rate an assistant message. Example identifiers and values are illustrative; substitute authorized values.
Render the returned stored rating state; the rating response contract defines replacement and the list of raters.
Variant: use a 1–10 scale instead of thumbs
Section ID: Guide/jcpe8h6c8i#two-rating-styles
Choose thumbs for a simple helpful/not-helpful choice, or a 1–10 scale for a more detailed survey. Use the corresponding rating fields.
Request example: Rate an assistant message. Example identifiers and values are illustrative; substitute authorized values.
Collect an optional explanation, especially when a reply did not help. Serialize rapid changes and show the stored result; attribution and ordering rules apply.
Restore the same feedback after reopening the conversation
Section ID: Guide/jcpe8h6c8i#reading-ratings-back
Load the conversation history and render its stored ratings; see feedback reads for the response field and supported write paths.
For aggregate analysis — how a profile scores across conversations, user ratings next to reviewer ratings — read them through the Evals scores API instead of walking conversations.
Let the user remove their judgment
Section ID: Guide/jcpe8h6c8i#withdraw-a-rating
When the user clears their selected rating, submit the withdrawal request below.
Request example: Withdraw your rating on a message. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Response:
Response example: Withdraw your rating on a message. Example identifiers and values are illustrative; substitute authorized values.
Reload the stored rating state after withdrawal. The withdrawal response distinguishes removal from an already-absent rating.
Document ID: Guide/jcpe8h6c8i