Reddit PM Bot for Freelance Outreach

A smart Reddit bot that scans subreddits for potential clients looking to hire developers, and sends personalized, human-like private messages.

Features

• Smart Post Detection: Uses keyword matching + OpenAI to identify genuine hiring posts
• Personalized Messages: Generates unique, human-like PMs for each post using GPT
• Rate Limiting: Respects Reddit's rules with built-in delays and limits
• Subreddit Cooldowns: Max 2 PMs per subreddit, then 24-hour cooldown
• Post Age Filter: Only responds to posts less than 1 hour old
• State Persistence: Tracks contacted users and processed posts to avoid duplicates
• Dry Run Mode: Test without sending actual messages

Prerequisites

1. Reddit Account with some karma (new accounts may be restricted from PMing)
2. Reddit API Credentials (free)
3. OpenAI API Key (for message generation)

Setup

1. Install Dependencies

cd reddit-pm-bot
npm install

2. Get Reddit API Credentials

Important: The developers.reddit.com site is for Devvit (Reddit's new app platform). For bot API credentials, you need the old apps page.

1. Log into Reddit first at https://www.reddit.com
2. Then go to: https://www.reddit.com/prefs/apps
   • If redirected to login, log in and try again
   • If you see "apps" page with your authorized apps, scroll down
3. Click "are you a developer? create an app..." or "create another app" (at the bottom)
4. Fill in:
   • Name: pm-bot (or any name)
   • App type: Select script (important - this is for personal bots)
   • Description: Optional
   • About URL: http://localhost (can be anything)
   • Redirect URI: http://localhost:8080 (required but not used for script apps)
5. Click "create app"
6. Note down your credentials:
   • Client ID: The string directly under the app name (looks like: aBcDeFgHiJkLmN)
   • Client Secret: The value next to "secret" (looks like: xYz123AbC456...)

Screenshot of where to find credentials:

pm-bot                          <-- Your app name
personal use script             <-- App type
aBcDeFgHiJkLmN                  <-- THIS IS YOUR CLIENT ID
                                
secret: xYz123AbC456DefGhi...   <-- THIS IS YOUR CLIENT SECRET

Troubleshooting:

• If you don't see the "create an app" option, try: https://old.reddit.com/prefs/apps
• Make sure you're logged into the Reddit account you want the bot to use
• Some new accounts may need to wait before creating apps
• Don't confuse this with developers.reddit.com - that's for Devvit (Reddit's new app platform), not API bots

Alternative: Using Reddit's API directly (if apps page doesn't work):

If you can't access the apps page, you can try using Reddit's public client:

1. Use client_id: YOUR_MANUAL_APP_ID (you still need to create an app)
2. Or contact Reddit at: https://www.reddithelp.com/hc/en-us/requests/new

3. Get OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Create a new API key
3. Add some credits ($5-10 is enough for thousands of messages)

4. Configure Environment

# Copy the example env file
cp .env.example .env

# Edit with your credentials

Edit .env:

REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USERNAME=your_reddit_username
REDDIT_PASSWORD=your_reddit_password
OPENAI_API_KEY=sk-your-openai-key

5. Customize Configuration

Edit config.js to:

• Update your freelancer profile
• Add/remove subreddits to monitor
• Adjust keywords for your services
• Change timing settings

Usage

Run Normally (Continuous Loop)

npm start

The bot will scan all configured subreddits every 5 minutes.

Run Once (Single Scan)

node bot.js --once

Dry Run (Test Mode)

node bot.js --dry-run --once

Shows what would be sent without actually sending PMs.

View Statistics

node bot.js --stats

Configuration Options

config.js

settings: {
  maxPostAge: 60,           // Only posts < 60 minutes old
  maxPMsPerSubreddit: 2,    // Max 2 PMs per subreddit
  cooldownHours: 24,        // 24hr cooldown after hitting limit
  checkIntervalSeconds: 300, // Check every 5 minutes
  pmDelaySeconds: 60,       // Wait 60s between PMs
  dryRun: false             // Set true to test
}

Customizing Subreddits

Add subreddits where your potential clients might post:

subreddits: [
  "forhire",      // General hiring
  "webdev",       // Web developers
  "startups",     // Startup founders
  // Add more...
]

Customizing Keywords

The bot uses two-stage filtering:

1. Keyword matching: Fast filtering for hiring intent + service keywords
2. AI analysis: Deeper analysis for borderline cases

Edit the keywords object in config.js to match your services.

How It Works

1. Scan: Fetches new posts from each configured subreddit
2. Filter:
   • Skips posts older than 1 hour
   • Skips already processed posts
   • Skips already contacted users
   • Checks for hiring intent keywords
   • Filters out "for hire" posts (people offering services)
3. Analyze: Uses OpenAI to verify the post is genuinely looking to hire
4. Generate: Creates a personalized PM using GPT
5. Send: Sends the PM and records it in state
6. Cooldown: After 2 PMs in a subreddit, waits 24 hours

Sample Generated PM

Hey, saw your post about needing a React developer for your startup dashboard. 
I've built similar analytics platforms with Next.js and have some ideas that 
could work well for your use case. Happy to chat if you want to see some 
examples from my portfolio at ahmerz.com.

Ahmer

Rate Limiting & Safety

• 1 second delay between Reddit API calls
• 60 second delay between sending PMs
• Max 2 PMs per subreddit per 24 hours
• Never contacts the same user twice
• Avoids posts where someone is offering services

Cost Estimates

• Reddit API: Free
• OpenAI: ~$0.01-0.02 per PM (using gpt-4o-mini)
• For 20 PMs/day: ~$6-12/month

Troubleshooting

"Invalid credentials"

• Double-check your Reddit username/password
• Make sure 2FA is disabled or use an app password

"Rate limit exceeded"

• The bot handles this automatically, but you might need to wait
• Reduce checkIntervalSeconds if it happens often

"User doesn't accept PMs"

• Some users disable PMs, this is handled gracefully

Messages sound too robotic

• Increase temperature in config (max 1.0)
• Edit the system prompt in openai-helper.js

Legal & Ethical Notes

• Respect Reddit's Terms of Service
• Don't spam - the 2 PM limit is intentionally conservative
• Be genuine - the bot generates personalized messages, not templates
• Provide value - only contact people you can genuinely help
• Be prepared to deliver - if someone responds, follow through professionally

License

MIT - Use responsibly!