Skip to main content

​
Quickstart Guide

Get your PFP Checker bot up and running in just a few minutes. This guide will take you from creating a Discord bot to monitoring your first user.

​
Prerequisites

Before you begin, you’ll need:
1

Discord Bot Token

You’ll need a Discord bot token from the Discord Developer Portal. If you don’t have one yet, we’ll create it in the next step.
2

ImgBB API Key

Profile pictures are stored on ImgBB. Get a free API key from ImgBB API. It’s free and takes less than a minute to sign up.
3

Docker (Recommended)

The easiest way to run PFP Checker is with Docker. Install Docker and Docker Compose for your platform.Alternatively, you can run it manually with Rust 1.86+ and SQLite installed.

​
Step 1: Create Your Discord Bot

1

Open Discord Developer Portal

Navigate to the Discord Developer Portal and click New Application.Give your application a name (e.g., “PFP Checker”) and accept the terms.
2

Create a Bot User

In the left sidebar, click Bot, then click Add Bot.Under the bot’s username, you’ll see a Token section. Click Reset Token and copy it. You’ll need this for your .env file.
Never share your bot token publicly! Treat it like a password. If it’s leaked, reset it immediately in the Developer Portal.
3

Configure Bot Permissions

Scroll down to Privileged Gateway Intents and ensure these are disabled (PFP Checker doesn’t need them):
  • Presence Intent
  • Server Members Intent
  • Message Content Intent
The bot only needs basic Discord API access to function.
4

Generate Invite Link

Go to OAuth2 → URL Generator in the left sidebar.Select the following scopes:
  • bot
  • applications.commands
Under Bot Permissions, select:
  • Read Messages/View Channels
Copy the generated URL at the bottom. You’ll use this to invite the bot to your server.

​
Step 2: Get Your ImgBB API Key

1

Sign Up for ImgBB

Go to ImgBB API and click Get API Key or sign in if you already have an account.
2

Copy Your API Key

After signing in, your API key will be displayed on the dashboard. Copy it for use in your .env file.
ImgBB’s free tier is more than sufficient for most use cases. Each profile picture upload counts against your quota.

​
Step 3: Deploy the Bot

# Clone the repository
git clone https://github.com/j4ytr1n1ty/pfp-checker.git
cd pfp-checker

# Create your environment file
cp .env.example .env

# Edit the .env file with your tokens
# DISCORD_TOKEN=your_discord_token_here
# IMGBB_KEY=your_imgbb_key_here
# DATABASE_URL=sqlite:database.sqlite

# Start the bot
docker-compose up -d

# Check that it's running
docker-compose logs -f
The first time you run the bot, SQLx will automatically create the SQLite database and run all migrations. You should see log messages confirming the database setup.

​
Step 4: Invite Bot to Your Server

1

Use the Invite Link

Open the OAuth2 URL you generated in Step 1 in your web browser.
2

Select a Server

Choose the server you want to add the bot to from the dropdown menu. You must have “Manage Server” permission on the server.
3

Authorize the Bot

Click Authorize and complete the CAPTCHA if prompted.You should see a confirmation message, and the bot will appear in your server’s member list.
4

Verify Bot is Online

In any channel, type /ping and press Enter.The bot should respond with:
🏓 Pong!
Latency: XXms
If you see this response, your bot is working correctly!

​
Step 5: Track Your First User

Now let’s monitor a user and view their profile picture history.
1

Start Monitoring a User

In any channel, use the /monitor command:
/monitor @username
Replace @username with any user in your server (you can tag yourself to test).The bot will respond:
Successfully added username to the monitoring list.
2

Wait for First Check

The bot checks for profile picture changes every 30 minutes. The first check will capture the user’s current profile picture and username as the baseline.
You won’t see any history until the first automatic check runs (within 30 minutes) or until the user actually changes their profile picture.
3

View Profile Picture History

After at least 30 minutes have passed, check the user’s history:
/pfphistory @username
You’ll see an embedded message showing all recorded profile pictures with:
  • Timestamp of when it was first recorded
  • Link to the archived image
  • SHA-1 checksum for verification
If there are more than 10 entries, use the Back and Next buttons to navigate pages.
4

Check Username History

You can also view username changes:
/usernamehistory @username
This shows all usernames the user has had since monitoring began.
5

View Statistics

Once the user has had at least 2 profile picture changes recorded, you can view statistics:
/stats @username
This displays:
  • Average time between profile picture changes (in hours and days)
  • Total number of changes since monitoring began
  • Date monitoring started

​
Step 6: Track Your Server

You can also monitor your server’s icon changes.
1

Enable Server Monitoring

Run this command in the server you want to track:
/monitorserver
You need “Manage Server” permission to enable server monitoring.
The bot will respond:
Successfully added [Server Name] to the server monitoring list.
2

View Server Icon History

After at least 30 minutes (or after the server icon changes), view the history:
/serverpfphistory
This shows all server icons with timestamps and archived links.
3

Check Server Statistics

View statistics about server icon changes:
/serverstats
Similar to user stats, this shows average change frequency and total count.

​
Quick Command Reference

CommandDescriptionExample
/pingCheck if bot is online/ping
/monitor @userStart tracking a user/monitor @john
/pfphistory @userView profile picture history/pfphistory @john
/usernamehistory @userView username history/usernamehistory @john
/stats @userView user statistics/stats @john
/monitorserverTrack this server’s icon/monitorserver
/serverpfphistoryView server icon history/serverpfphistory
/serverstatsView server statistics/serverstats
/removemonitor @userStop tracking a user/removemonitor @john
/removemonitorserverStop tracking this server/removemonitorserver

​
Troubleshooting

​
Bot doesn’t respond to commands

  1. Verify the bot is online (green status in member list)
  2. Check Docker logs: docker-compose logs -f
  3. Ensure the bot has permission to read messages in the channel
  4. Verify your Discord token is correct in .env

​
”No history found” message

This is normal if:
  • Less than 30 minutes have passed since adding the user/server
  • The user/server hasn’t changed their picture since monitoring began
Wait at least 30 minutes for the first automatic check to complete.

​
Images not uploading

  1. Verify your ImgBB API key is correct in .env
  2. Check that you haven’t exceeded ImgBB’s rate limits
  3. Restart the bot after updating .env: docker-compose restart

​
Next Steps

Full Installation Guide

Learn about production deployment and advanced configuration

All Commands

Explore all available commands in detail

Build docs developers (and LLMs) love

Get started for freeTalk to us