Skip to main content

Collect message feedback

Section: DOC-IS-evaluation-message-feedback#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: DOC-IS-evaluation-message-feedback#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.

  1. Keep the conversation key and assistant message sequence with the rendered reply.
  2. Authenticate the rater; do not let the client supply another person as the author.
  3. Submit the selected rating below and render the returned stored result.
  4. On a lost response, reload the conversation’s ratings before sending another change.
  5. 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.

curl -X POST https://api.travila.ai/api/v1/llm/rate-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "messageSequence": 8,
  "kind": "FEEDBACK_KIND_THUMB",
  "thumbUp": true
}'

Reference: Rate an assistant message · Request fields.

Response:

{
  "ratedMessage": {
    "role": "ROLE_ASSISTANT",
    "sequence": "8",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "…"
      }
    ],
    "feedback": [
      {
        "kind": "FEEDBACK_KIND_THUMB",
        "thumbUp": true,
        "ratedAt": "2026-08-14T11:02:44Z",
        "ratedBy": "user_123"
      }
    ]
  },
  "isUpdate": true
}

Reference: Rate an assistant message · Response fields.

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: DOC-IS-evaluation-message-feedback#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.

{
  "conversationKey": "support-chat-001",
  "messageSequence": 8,
  "kind": "FEEDBACK_KIND_SCALE",
  "rating": 9,
  "reason": "Answered the question and cited the policy."
}

Reference: Rate an assistant message · Request fields.

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: DOC-IS-evaluation-message-feedback#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: DOC-IS-evaluation-message-feedback#withdraw-a-rating.

When the user clears their selected rating, submit the withdrawal request below.

curl -X POST https://api.travila.ai/api/v1/llm/delete-message-rating \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "messageSequence": 8
}'

Reference: Withdraw your rating on a message · Request fields.

Response:

{
  "ratedMessage": {
    "role": "ROLE_ASSISTANT",
    "sequence": "8",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "…"
      }
    ]
  },
  "removed": true
}

Reference: Withdraw your rating on a message · Response fields.

Reload the stored rating state after withdrawal. The withdrawal response distinguishes removal from an already-absent rating.

Document ID: DOC-IS-evaluation-message-feedback. Section identities and revisions.