Bluesky Integration - Quick Start

Setup Instructions

1. Create Bluesky Bot Account

1. Go to https://bsky.app and create a new account (or use existing)
2. Navigate to Settings → App Passwords
3. Click "Add App Password"
4. Give it a name (e.g., "TrackFox Bot")
5. Copy the generated password (you won't see it again!)

2. Environment Variables

Add these to your .env.local file:

# Bluesky Configuration
BSKY_PDS=https://bsky.social
BSKY_IDENTIFIER=your-handle.bsky.social
BSKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

# Cron Security (generate with: openssl rand -base64 32)
CRON_SECRET=your-random-secret-here

Replace:

• your-handle.bsky.social with your bot's Bluesky handle
• xxxx-xxxx-xxxx-xxxx with the app password you generated
• your-random-secret-here with a secure random string

3. Deploy

1. Commit changes: git add . && git commit -m "Add Bluesky integration"
2. Push to your repository: git push
3. Vercel will automatically deploy with the cron job configured

4. Configure Cron Secret on Vercel

1. Go to your Vercel project → Settings → Environment Variables
2. Add CRON_SECRET with your secret value
3. Redeploy the project

5. Test the Integration

⚠️ Note: The dashboard viewing feature is currently only available in development mode.

Add a Keyword

1. Go to your TrackFox dashboard (works in all environments)
2. Navigate to Settings → Integrations → Bluesky tab
3. Add a keyword (e.g., your brand name)

Trigger Cron Manually (Optional)

curl -H "Authorization: Bearer YOUR_CRON_SECRET" \
  https://your-domain.vercel.app/api/bsky/search

View Mentions (Development Only)

1. Make sure you're running in development mode: NODE_ENV=development
2. Wait a few minutes for the cron to run
3. Go to Dashboard → Bluesky Mentions
4. You should see posts matching your keywords!

In production: The "View All Mentions" link will be hidden until the feature is fully released.

File Structure

app/
├── api/
│   └── bsky/
│       ├── keywords/
│       │   ├── route.ts (GET, POST)
│       │   └── [id]/route.ts (DELETE)
│       ├── posts/route.ts (GET)
│       └── search/route.ts (Cron)
├── dashboard/
│   └── [id]/
│       └── bluesky/page.tsx

components/
├── BlueskyIntegrationCard.tsx
├── BlueskyKeywordItem.tsx
└── dashboard/
    ├── BlueskyDashboard.tsx
    └── BlueskyPostCard.tsx

models/
├── bsky-keyword.ts
└── bsky-post.ts

lib/
├── bsky.ts (auth helpers)
└── bsky-utils.ts (utility functions)

Troubleshooting

"Unauthorized" error

• Check if BSKY_IDENTIFIER and BSKY_APP_PASSWORD are correct
• Verify the app password hasn't been revoked on Bluesky

Cron not running

• Check Vercel dashboard → Cron Jobs tab
• Verify vercel.json is in the root directory
• Make sure project is deployed

No posts appearing

• Add keywords in Settings → Integrations
• Wait for next hourly cron run (top of each hour)
• Check logs in Vercel dashboard for errors

Keywords not saving

• Verify you're the website owner (not a team member)
• Check if you've already added 5 keywords (max limit)
• Ensure keyword is 1-100 characters

Need Help?

Check the full documentation: docs/bluesky-integration.md