Conversation Feedback
Feedback mechanisms in conversations enable users to rate AI responses and provide valuable signals about response quality, helpfulness, and accuracy. The platform supports both upvotes (positive feedback) and downvotes (negative feedback), with optional reasons to provide context for the rating.
Collecting feedback helps you understand which interactions are successful and which need improvement, enabling data-driven optimization of your AI bots. The feedback system tracks ratings per conversation and implements rate limiting to prevent abuse while allowing legitimate user feedback.
Upvoting a Conversation
An upvote indicates positive feedback about a conversation, signaling that the AI responses were helpful, accurate, or met the user's needs. Upvotes can include an optional value (1-100) to indicate varying degrees of satisfaction and an optional reason explaining why the conversation was rated positively.
To upvote a conversation:
Replace {conversationId} with the actual conversation ID. Both fields are
optional, with value defaulting to 100 if not specified.
Upvote Parameters
When submitting an upvote, you can specify:
-
value: Integer from 1 to 100 indicating satisfaction level (default: 100)
- 100: Excellent, exceeded expectations
- 75-99: Very good, met expectations well
- 50-74: Good, adequately met expectations
- 1-49: Acceptable, minimally met expectations
-
reason: Optional text explaining why the conversation was rated positively. This provides valuable context for analyzing successful interactions and identifying what works well.
What Happens During an Upvote
When a conversation is upvoted:
- The system verifies you have permission to rate the conversation
- Rate limiting is checked to prevent duplicate ratings
- Activity messages are added to the conversation documenting the upvote
- A rating record is created linking the vote to the user, bot, contact, and conversation
- The rating becomes available for analytics and reporting
Use Cases for Upvotes
Upvotes are valuable for:
- Quality Metrics: Tracking overall bot performance and user satisfaction
- Success Identification: Finding exemplary conversations that can inform training and improvements
- User Engagement: Encouraging users to provide positive feedback
- A/B Testing: Comparing satisfaction levels between different bot configurations
- Training Data: Identifying high-quality conversations for model training or prompt refinement
Response
The API returns:
This confirms which conversation was upvoted and can be used for UI feedback or logging purposes.
Important Notes:
- Upvotes are rate-limited to prevent abuse - users can only vote once per conversation within a time window
- If rate limiting is triggered, the API still returns success but does not record the duplicate vote
- Upvote activity is recorded in the conversation's message history
- The rating is associated with the bot, allowing for cross-conversation analytics
- You can only upvote conversations that belong to your account
Downvoting a Conversation
A downvote indicates negative feedback about a conversation, signaling that the AI responses were unhelpful, inaccurate, or failed to meet the user's needs. Downvotes provide critical insights into where your AI bot needs improvement and help identify problematic interaction patterns.
To downvote a conversation:
Replace {conversationId} with the actual conversation ID. Both fields are
optional, with value defaulting to -100 if not specified.
Downvote Parameters
When submitting a downvote, you can specify:
-
value: Integer from -100 to -1 indicating dissatisfaction level (default: -100)
- -100: Very poor, completely failed to meet expectations
- -75 to -99: Poor, significantly below expectations
- -50 to -74: Below expectations, multiple issues
- -1 to -49: Somewhat disappointing, minor issues
-
reason: Optional text explaining why the conversation was rated negatively. This is especially valuable for downvotes as it provides specific, actionable feedback about what went wrong.
What Happens During a Downvote
When a conversation is downvoted:
- The system verifies you have permission to rate the conversation
- Rate limiting is checked to prevent duplicate ratings
- Activity messages are added to the conversation documenting the downvote
- A rating record is created with a negative value, linking the vote to the user, bot, contact, and conversation
- The negative rating becomes available for analytics and improvement analysis
Value of Downvote Reasons
Providing detailed reasons for downvotes is particularly valuable because it:
- Identifies Specific Issues: Explains exactly what went wrong
- Enables Targeted Improvements: Helps focus optimization efforts
- Reveals Pattern Problems: Shows recurring issues across conversations
- Guides Training: Informs prompt engineering and model fine-tuning
- Improves User Experience: Demonstrates that feedback is valued and actionable
Common Downvote Reasons
Examples of valuable downvote feedback:
- "The assistant didn't understand my technical question"
- "Responses were too generic and not specific to my situation"
- "The bot provided outdated or incorrect information"
- "I couldn't get a direct answer to my question"
- "The conversation required too many back-and-forth exchanges"
- "The tone was inappropriate for my needs"
Use Cases for Downvotes
Downvotes are essential for:
- Problem Identification: Finding conversations where the AI failed to meet expectations
- Quality Assurance: Monitoring for systematic issues or degraded performance
- Improvement Prioritization: Identifying which aspects of bot behavior need the most urgent attention
- Training Data: Finding negative examples to avoid during model training
- User Satisfaction Tracking: Understanding the rate and reasons for user dissatisfaction
- A/B Testing: Identifying which configurations lead to more negative feedback
Analyzing Downvote Feedback
To effectively use downvote data:
- Review Conversations: Examine downvoted conversations to understand what went wrong
- Categorize Issues: Group downvotes by reason to identify common problems
- Measure Impact: Track downvote rates over time to assess improvement efforts
- Prioritize Fixes: Address issues causing the most frequent or severe downvotes first
- Test Solutions: Verify that changes reduce downvote rates for similar scenarios
Response
The API returns:
This confirms which conversation was downvoted and can be used for logging, analytics, or triggering follow-up actions.
Rate Limiting and Abuse Prevention
Like upvotes, downvotes are rate-limited to prevent abuse:
- Users can only vote once per conversation within a time window
- Duplicate downvote attempts are silently rejected but return success
- This prevents malicious users from repeatedly downvoting conversations
- Legitimate users can still provide feedback on new conversations
Best Practices:
- Always encourage users to provide reasons when downvoting
- Make it easy for users to submit feedback at natural conversation endpoints
- Review downvoted conversations regularly to identify improvement opportunities
- Use downvote patterns to guide bot configuration and prompt refinement
- Consider following up with users who downvote to better understand their needs
- Track downvote rates over time as a key performance indicator
Important Notes:
- Downvotes are permanent once recorded and cannot be changed to upvotes
- Downvote activity is recorded in the conversation's message history for audit purposes
- The rating is associated with the bot, enabling cross-conversation analysis
- You can only downvote conversations that belong to your account
- Rate limiting prevents duplicate votes but doesn't prevent legitimate feedback on different conversations