Text Responses

Detailed guide to implementing free-form text responses for collecting detailed feedback and explanations from reviewers

Text Responses

Text responses allow reviewers to provide free-form written feedback, making them perfect for scenarios requiring detailed explanations, qualitative assessments, or open-ended input that can’t be captured through structured options.

When to Use Text Responses

Text responses are ideal for:

Content Review Feedback

Detailed feedback on articles, blog posts, or creative content where specific suggestions and explanations are valuable.

Quality Assessments

Explanations of why something passed or failed review, with specific recommendations for improvement.

Issue Reporting

Describing problems, bugs, or policy violations where context and detail are crucial for understanding.

Expert Analysis

Professional opinions, technical assessments, or domain expert evaluations requiring nuanced explanations.

Configuration Options

Text responses support several configuration parameters to control input validation and user experience:

Required Parameters

max_length · integer · required

Maximum number of characters allowed (1-5000)

Optional Parameters

placeholder · string

Placeholder text shown in the input field to guide reviewers

min_length · integer · default: "0"

Minimum number of characters required for the response

required · boolean · default: "false"

Whether the response is mandatory or can be left empty

Implementation Examples

Basic Text Response

Simple text feedback with basic validation:

Python

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "medium",
    "request_text": "Please review this blog post and provide feedback on accuracy, tone, and readability.",
    "response_type": "text",
    "response_config": {
        "max_length": 1000,
        "placeholder": "Provide your detailed feedback here...",
        "required": True
    },
    "default_response": "No feedback provided within the review period",
    "timeout_seconds": 3600,
    "platform": "api"
}

const requestData = {
    processing_type: "time-sensitive",
    type: "markdown", 
    priority: "medium",
    request_text: "Please review this blog post and provide feedback on accuracy, tone, and readability.",
    response_type: "text",
    response_config: {
        max_length: 1000,
        placeholder: "Provide your detailed feedback here...",
        required: true
    },
    default_response: "No feedback provided within the review period",
    timeout_seconds: 3600,
    platform: "api"
};

curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "medium", 
    "request_text": "Please review this blog post and provide feedback on accuracy, tone, and readability.",
    "response_type": "text",
    "response_config": {
        "max_length": 1000,
        "placeholder": "Provide your detailed feedback here...",
        "required": true
    },
    "default_response": "No feedback provided within the review period",
    "timeout_seconds": 3600,
    "platform": "api"
  }'

Advanced Text Response

Text response with length requirements and structured guidance:

Python

# Content editing request with detailed requirements
request_data = {
    "processing_type": "deferred",
    "type": "markdown",
    "priority": "low",
    "request_text": """
Please edit this article draft and provide improvement suggestions:

# Article Title: "10 Ways to Improve Your Productivity"

Content here would be the actual article...

Please focus on:
1. Grammar and spelling corrections
2. Flow and readability improvements  
3. Factual accuracy
4. Engagement and tone
""",
    "response_type": "text",
    "response_config": {
        "placeholder": "Provide specific editing suggestions with line references where possible. Format: '1. Grammar: Fix X in paragraph 2. 2. Flow: Restructure Y section...'",
        "min_length": 100,
        "max_length": 2000,
        "required": True
    },
    "default_response": "Editorial review not completed within deadline. Recommend postponing publication pending review.",
    "timeout_seconds": 86400,  # 24 hours
    "platform": "api"
}

// Code review feedback request
const requestData = {
    processing_type: "time-sensitive",
    type: "markdown",
    priority: "high",
    request_text: `Please review this code change and provide feedback:

\`\`\`javascript
// Code diff or snippet here
function processUserData(userData) {
    // Implementation details...
}
\`\`\`

Focus on security, performance, and maintainability.`,
    response_type: "text",
    response_config: {
        placeholder: "Provide specific feedback on security vulnerabilities, performance issues, code quality, and suggested improvements...",
        min_length: 50,
        max_length: 1500,
        required: true
    },
    default_response: "Code review not completed within deadline. Do not merge pending review.",
    timeout_seconds: 7200, // 2 hours
    platform: "api"
};

Response Format

When a reviewer submits a text response, you’ll receive:

{
  "response_data": "The article is well-structured and informative. Grammar is mostly correct with a few minor issues: 'it's' should be 'its' in paragraph 3, and there's a comma splice in the conclusion. The tone is engaging and appropriate for the target audience. I'd recommend adding one more concrete example in section 4 to strengthen the argument. Overall, this is ready for publication with those minor corrections."
}

Use Case Examples

1. Content Editorial Review

Configuration

editorial_config = {
    "response_type": "text",
    "response_config": {
        "placeholder": "Provide editorial feedback covering grammar, style, accuracy, and engagement. Include specific suggestions for improvement.",
        "min_length": 50,
        "max_length": 1200,
        "required": True
    },
    "default_response": "Editorial review incomplete - recommend additional review before publication"
}

Sample Response

{
  "response_data": "Article structure is solid with clear progression. Grammar issues: 'affect' vs 'effect' in para 2, missing serial comma in bullet list. Style: tone shifts between formal/casual - recommend consistency. Content accuracy verified against cited sources. Suggest stronger opening hook and more specific examples in conclusion. Overall grade: B+ with recommended revisions."
}

Processing

def process_editorial_feedback(response_data):
    feedback = response_data
    
    # Parse feedback for common patterns
    if "grammar issues:" in feedback.lower():
        flag_for_copy_editing()
    
    if "accuracy verified" in feedback.lower():
        mark_factually_approved()
    
    if "grade: a" in feedback.lower():
        approve_for_publication()
    elif "grade: b" in feedback.lower():
        require_minor_revisions()
    else:
        require_major_revisions()
    
    # Store full feedback for author
    save_feedback_for_author(feedback)

2. Bug Report Verification

Configuration

bug_verification_config = {
    "response_type": "text", 
    "response_config": {
        "placeholder": "Describe steps taken to reproduce the bug, environment details, and whether you confirmed the issue. Include severity assessment.",
        "min_length": 75,
        "max_length": 800,
        "required": True
    },
    "default_response": "Bug verification not completed within SLA timeframe"
}

Sample Response

{
  "response_data": "Reproduced on Chrome 120.0, Firefox 119.0, Safari 17.1 using provided steps. Issue occurs consistently when user has >100 items in cart. Error appears in console: 'Cannot read property length of undefined' in checkout.js:247. Workaround: clear cart and re-add items. Severity: Medium - affects checkout but has workaround. Recommend priority fix for next sprint."
}

Processing

def process_bug_verification(response_data):
    feedback = response_data
    
    # Extract severity
    if "severity: critical" in feedback.lower():
        set_bug_priority("P0")
    elif "severity: high" in feedback.lower():
        set_bug_priority("P1") 
    elif "severity: medium" in feedback.lower():
        set_bug_priority("P2")
    else:
        set_bug_priority("P3")
    
    # Check if reproduced
    if "reproduced" in feedback.lower():
        confirm_bug_exists()
    elif "cannot reproduce" in feedback.lower():
        mark_as_works_as_designed()
    
    # Store detailed feedback
    update_bug_report(feedback)

3. Expert Consultation

Configuration

expert_consultation_config = {
    "response_type": "text",
    "response_config": {
        "placeholder": "Provide your expert analysis including key insights, recommendations, risk assessment, and suggested next steps. Include confidence level in your assessment.",
        "min_length": 200,
        "max_length": 3000,
        "required": True
    },
    "default_response": "Expert consultation not completed within consultation period"
}

Sample Response

{
  "response_data": "Technical Analysis: The proposed architecture shows good scalability patterns but has potential security vulnerabilities in the API gateway layer. Recommendations: 1) Implement OAuth 2.0 with PKCE, 2) Add rate limiting per endpoint, 3) Consider edge caching for static content. Risk Assessment: Medium risk if deployed as-is, low risk with recommended changes. Cost implications: Additional $2-3k monthly for security infrastructure. Timeline: 2-3 weeks for full implementation. Confidence: High (8/10) based on similar implementations. Next steps: Security audit, load testing, phased rollout."
}

Processing

def process_expert_consultation(response_data):
    feedback = response_data
    
    # Extract confidence level
    import re
    confidence_match = re.search(r'confidence[:\s]+(?:high|medium|low|\d+/10)', feedback.lower())
    if confidence_match:
        confidence = confidence_match.group()
        store_confidence_rating(confidence)
    
    # Extract recommendations
    if "recommendations:" in feedback.lower():
        recommendations_section = extract_section_after("recommendations:", feedback)
        parse_recommendations(recommendations_section)
    
    # Flag for executive summary if high-stakes
    if "risk assessment: high" in feedback.lower():
        escalate_to_executives()
    
    # Store full consultation
    save_expert_consultation(feedback)

Validation and Error Handling

Client-Side Validation

The mobile app automatically validates text responses:

• Length checking: Prevents submission if outside min/max bounds
• Required validation: Blocks empty submissions when required=true
• Character counting: Shows real-time character count to reviewers
• Whitespace handling: Trims leading/trailing whitespace before validation

Server-Side Validation

Your application should also validate responses:

def validate_text_response(response_data, response_config):
    """Validate text response against configuration"""
    
    if not isinstance(response_data, str):
        return False, "Response must be text"
    
    # Check required
    if response_config.get("required", False) and not response_data.strip():
        return False, "Response is required"
    
    # Check length bounds
    text_length = len(response_data.strip())
    min_length = response_config.get("min_length", 0)
    max_length = response_config.get("max_length", 5000)
    
    if text_length < min_length:
        return False, f"Response too short (minimum {min_length} characters)"
    
    if text_length > max_length:
        return False, f"Response too long (maximum {max_length} characters)"
    
    return True, "Valid"

# Usage
is_valid, error_message = validate_text_response(
    response_data="This is the reviewer's feedback...",
    response_config={
        "min_length": 20,
        "max_length": 500,
        "required": True
    }
)

Best Practices

Configuration Best Practices

Set Reasonable Length Limits

• Short feedback: 50-300 characters for quick comments
• Detailed reviews: 200-1500 characters for thorough analysis
• Expert consultations: 500-3000 characters for comprehensive assessments
• Avoid extremes: too short limits valuable feedback, too long reduces completion rates

Provide Clear Guidance

• Use descriptive placeholders that explain what you’re looking for
• Include examples of good feedback in the request_text
• Specify focus areas or structured format when helpful
• Guide reviewers on the level of detail expected

Consider Review Context

• Time-sensitive requests: shorter responses, clear urgency indicators
• Expert reviews: longer limits, domain-specific guidance
• Quality checks: structured feedback requests with specific criteria
• Editorial reviews: formatting suggestions and style guide references

Processing Best Practices

Automated Analysis

# Extract actionable insights from text feedback
def analyze_text_feedback(feedback_text):
    insights = {
        "sentiment": analyze_sentiment(feedback_text),
        "action_items": extract_action_items(feedback_text), 
        "mentioned_issues": identify_issues(feedback_text),
        "confidence_indicators": find_confidence_signals(feedback_text)
    }
    return insights

Feedback Aggregation

# Combine multiple text responses for consensus
def aggregate_text_responses(responses):
    common_themes = identify_common_themes(responses)
    conflicting_opinions = find_disagreements(responses)
    
    return {
        "consensus_points": common_themes,
        "areas_of_disagreement": conflicting_opinions,
        "recommendation": generate_final_recommendation(responses)
    }

Quality Scoring

# Score text response quality and usefulness
def score_response_quality(response_text, criteria):
    scores = {}
    
    # Length appropriateness
    scores["length"] = evaluate_response_length(response_text)
    
    # Specificity and actionability  
    scores["specificity"] = count_specific_examples(response_text)
    
    # Coverage of requested criteria
    scores["coverage"] = check_criteria_coverage(response_text, criteria)
    
    return calculate_overall_score(scores)

Next Steps

Single Select Responses

Learn about structured decision-making with predefined options

Multi Select Responses

Combine text feedback with categorical selections

Response Processing

Understand how to handle and analyze different response types

Mobile App Experience

See how reviewers interact with text responses on mobile