Skip to main content
PUT
Rate Message

Rate Message

Rate an AI-generated message to provide feedback on the quality of the response. This helps improve the AI agent’s performance and track user satisfaction.

Endpoint

Authentication

string
required
Your Nexus API key for authentication

Path Parameters

string
required
The ID of the AI message to rate. This must be a message generated by the AI assistant, not a user message.

Request Body

number
required
The rating score from 1 to 5, where:
  • 1 = Very Poor
  • 2 = Poor
  • 3 = Average
  • 4 = Good
  • 5 = Excellent
string
Optional text feedback providing additional context about the rating. Maximum length: 1000 characters.

Response Fields

string
required
Unique identifier for the rating
string
required
The ID of the message that was rated
number
required
The rating score provided (1-5)
string
The optional feedback text if provided
string
required
ISO 8601 timestamp of when the rating was created
string
required
ISO 8601 timestamp of when the rating was last updated

Example Usage

Rating Guidelines

When to Rate Messages

  • After receiving a response: Rate immediately after receiving an AI response while the context is fresh
  • Quality feedback: Provide ratings that reflect the actual helpfulness of the response
  • Update ratings: You can update a previous rating by calling the endpoint again with the same message ID

Score Guidelines

Common Patterns

1. Rate After Response Pattern

2. Feedback Collection Pattern

3. Batch Rating Pattern

Error Responses

Best Practices

  • Provide honest and accurate ratings
  • Include specific feedback when possible
  • Rate based on the actual helpfulness of the response
  • Consider the context of the conversation
  • Keep feedback constructive and specific
  • Mention what was good or what could be improved
  • Avoid personal information in feedback
  • Use clear and concise language
  • Store message IDs for later rating
  • Implement rating UI in your application
  • Handle rating errors gracefully
  • Consider implementing a rating reminder system
  • Track rating patterns over time
  • Monitor average scores by conversation type
  • Use feedback to identify improvement areas
  • Correlate ratings with user engagement

Limitations

  • Message Type: Only AI-generated messages can be rated (not user messages)
  • Score Range: Score must be an integer between 1 and 5
  • Feedback Length: Maximum 1000 characters for feedback text
  • Update Behavior: Rating the same message again will update the existing rating
  • Integration Scope: You can only rate messages from your own integration