freealberta/influence/RESPONSE_WALL_USAGE.md

Response Wall - Usage Guide

Overview

The Response Wall is now fully implemented! It allows campaign participants to share and vote on responses they receive from elected representatives.

How to Access the Response Wall

The Response Wall requires a campaign slug to function. You must access it with a URL parameter:

URL Format

http://localhost:3333/response-wall.html?campaign=YOUR-CAMPAIGN-SLUG

Example URLs

http://localhost:3333/response-wall.html?campaign=climate-action
http://localhost:3333/response-wall.html?campaign=healthcare-reform
http://localhost:3333/response-wall.html?campaign=education-funding

Setup Instructions

1. Create a Campaign First

Before using the Response Wall, you need to have an active campaign:

1. Go to http://localhost:3333/admin.html
2. Create a new campaign with a slug (e.g., "climate-action")
3. Note the campaign slug you created

2. Access the Response Wall

Use the campaign slug in the URL:

http://localhost:3333/response-wall.html?campaign=YOUR-SLUG-HERE

Features

For Public Users

• View Responses: See all approved responses from representatives
• Filter & Sort:
  • Filter by government level (Federal, Provincial, Municipal, School Board)
  • Sort by Most Recent, Most Upvoted, or Verified First
• Submit Responses: Share responses you've received from representatives
  • Required: Representative name, level, response type, response text
  • Optional: Representative title, your comment, screenshot, your name/email
  • Can post anonymously
• Upvote Responses: Show appreciation for helpful responses
• View Statistics: See total responses, verified count, and total upvotes

For Administrators

Access via the admin panel at http://localhost:3333/admin.html:

1. Navigate to the "Response Moderation" tab
2. Filter by status: Pending, Approved, Rejected, or All
3. Moderate submissions:
   • Approve: Make response visible to public
   • Reject: Hide inappropriate responses
   • Verify: Add verification badge to authentic responses
   • Edit: Modify response content if needed
   • Delete: Remove responses permanently

Moderation Workflow

1. User submits a response (status: "pending")
2. Admin reviews in admin panel → "Response Moderation" tab
3. Admin approves → Response appears on public Response Wall
4. Admin can mark as "verified" for authenticity badge
5. Public can upvote helpful responses

Integration with Campaigns

Link from Campaign Pages

You can add links to the Response Wall from your campaign pages:

<a href="/response-wall.html?campaign=YOUR-SLUG">
  View Community Responses
</a>

Embed in Campaign Flow

Consider adding a "Share Your Response" call-to-action after users send emails to representatives.

Testing the Feature

1. Create Test Campaign

# Via admin panel or API
POST /api/admin/campaigns
{
  "title": "Test Campaign",
  "slug": "test-campaign",
  "email_subject": "Test",
  "email_body": "Test body"
}

2. Submit Test Response

Navigate to:

http://localhost:3333/response-wall.html?campaign=test-campaign

Click "Share a Response" and fill out the form.

3. Moderate Response

1. Go to admin panel: http://localhost:3333/admin.html
2. Click "Response Moderation" tab
3. Change filter to "Pending"
4. Approve the test response

4. View Public Response

Refresh the Response Wall page to see your approved response.

API Endpoints

Public Endpoints

• GET /api/campaigns/:slug/responses - Get approved responses
• GET /api/campaigns/:slug/response-stats - Get statistics
• POST /api/campaigns/:slug/responses - Submit new response
• POST /api/responses/:id/upvote - Upvote a response
• DELETE /api/responses/:id/upvote - Remove upvote

Admin Endpoints (require authentication)

• GET /api/admin/responses - Get all responses (any status)
• PATCH /api/admin/responses/:id/status - Update status
• PATCH /api/admin/responses/:id - Update response details
• DELETE /api/admin/responses/:id - Delete response

Database Tables

The feature uses two new NocoDB tables:

influence_representative_responses

Stores submitted responses with fields:

• Representative details (name, title, level)
• Response content (type, text, screenshot)
• Submitter info (name, email, anonymous flag)
• Moderation (status, verified flag)
• Engagement (upvote count)

influence_response_upvotes

Tracks upvotes with fields:

• Response ID
• User ID / Email (if authenticated)
• IP address (for anonymous upvotes)

Troubleshooting

"No campaign specified" Error

Problem: Accessing /response-wall.html without campaign parameter

Solution: Add ?campaign=YOUR-SLUG to the URL

No Responses Showing

Problem: Responses exist but not visible

Possible Causes:

1. Responses are in "pending" status (not yet approved by admin)
2. Wrong campaign slug in URL
3. Responses filtered out by current filter settings

Solution:

• Check admin panel → Response Moderation tab
• Verify campaign slug matches
• Clear filters (set to "All Levels")

Button Not Working

Problem: "Share a Response" button doesn't open modal

Solution:

• Check browser console for JavaScript errors
• Verify you're accessing with a valid campaign slug
• Hard refresh the page (Ctrl+F5)

Images Not Uploading

Problem: Screenshot upload fails

Possible Causes:

1. File too large (max 5MB)
2. Wrong file type (only JPEG/PNG/GIF/WebP allowed)
3. Upload directory permissions

Solution:

• Resize image to under 5MB
• Convert to supported format
• Check /app/public/uploads/responses/ directory exists with write permissions

Next Steps

1. Run Database Setup: ./scripts/build-nocodb.sh (if not already done)
2. Restart Application: docker compose down && docker compose up --build
3. Create Test Campaign: Via admin panel
4. Test Response Submission: Submit and moderate a test response
5. Integrate with Campaigns: Add Response Wall links to your campaign pages

Notes

• All submissions require admin moderation (status: "pending" → "approved")
• Anonymous upvotes are tracked by IP address to prevent duplicates
• Authenticated upvotes are tracked by user ID
• Screenshots are stored in /app/public/uploads/responses/
• The feature respects NocoDB best practices (column titles, system fields, etc.)