Skip to main content
PUT
/
api
/
public
/
messages
/
{messageId}
/
rate
Rate Message
curl --request PUT \
  --url https://api.nexusgpt.io/api/public/messages/{messageId}/rate \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "score": 123,
  "feedback": "<string>"
}
'
{
  "id": "rating-550e8400-e29b-41d4",
  "messageId": "msg-123456789",
  "score": 5,
  "feedback": "Very helpful and accurate response!",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
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

PUT https://api.nexusgpt.io/api/public/messages/{messageId}/rate

​
Authentication

​
api-key
string
required
Your Nexus API key for authentication

​
Path Parameters

​
messageId
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

​
score
number
required
The rating score from 1 to 5, where:
  • 1 = Very Poor
  • 2 = Poor
  • 3 = Average
  • 4 = Good
  • 5 = Excellent
​
feedback
string
Optional text feedback providing additional context about the rating. Maximum length: 1000 characters.
{
  "id": "rating-550e8400-e29b-41d4",
  "messageId": "msg-123456789",
  "score": 5,
  "feedback": "Very helpful and accurate response!",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Response Fields

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

​
Example Usage

curl -X PUT https://api.nexusgpt.io/api/public/messages/msg-123456789/rate \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "score": 5,
    "feedback": "Very helpful and accurate response!"
  }'

​
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

ScoreDescriptionWhen to Use
5ExcellentPerfect response, fully addresses the query, accurate and helpful
4GoodMostly accurate and helpful with minor room for improvement
3AverageAdequate response but missing some details or partially helpful
2PoorResponse has significant issues or is mostly unhelpful
1Very PoorCompletely wrong, irrelevant, or unhelpful response

​
Common Patterns

​
1. Rate After Response Pattern

async function interactAndRate(sessionId, userMessage) {
  // Send message
  await sendMessage(sessionId, userMessage);
  
  // Get response
  const messages = await getMessages(sessionId, { limit: 2, order: 'desc' });
  const aiResponse = messages.find(m => m.type === 'assistant');
  
  // Rate the response based on quality
  if (aiResponse) {
    const score = evaluateResponse(aiResponse.content);
    await rateMessage(aiResponse.id, score);
  }
}

​
2. Feedback Collection Pattern

async function collectUserFeedback(messageId) {
  // Show rating UI to user
  const { score, feedback } = await showRatingDialog();
  
  // Submit rating with optional feedback
  try {
    const rating = await rateMessage(messageId, score, feedback);
    console.log('Thank you for your feedback!');
    return rating;
  } catch (error) {
    console.error('Failed to submit rating:', error);
  }
}

​
3. Batch Rating Pattern

async function rateMultipleMessages(ratings) {
  const results = [];
  
  for (const { messageId, score, feedback } of ratings) {
    try {
      const result = await rateMessage(messageId, score, feedback);
      results.push({ success: true, rating: result });
    } catch (error) {
      results.push({ success: false, messageId, error: error.message });
    }
  }
  
  return results;
}

​
Error Responses

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
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