Disclaimer Warning: This script may breach X's Terms of Service contract that you agreed to when creating an account. It was made for educational & informational purposes.
This project is a Python script designed to send direct messages (DMs) to followers on X (formerly known as Twitter) using a headless browser. The script logs into your X account, fetches a list of your followers, and sends a predefined message to each follower.
This script works well for X accounts with fewer than ~1,000 followers.
For accounts with more than ~1,000 followers, use the X-ID2Username tool to generate a followers.txt list of usernames. This tool extracts usernames from the follower.js file included in your X Data Archive download. More info below
This script does NOT use the X API, as the free tier doesn’t allow sending DMs. Instead, it uses a (headless) browser to log in, fetch followers, and send DMs.
- Headless Browser: Uses Selenium with a headless Chrome browser for automation.
- Configurable: Allows customization of DM intervals, retry attempts, maximum followers to process, and more via a config file.
- Progress Tracking: Saves progress to avoid messaging the same follower more than once.
- Screenshot Option: Can take screenshots at various stages for debugging purposes.
- Message Verification: Verifies the message by checking the first few words of the predefined message in the DM. (Current version has some issues with this, but still knows when it's a success)
- Can use followers.txt: Supports importing a
followers.txtusername list generated by the X-ID2Username tool. This tool converts user links from thefollower.jsfile — provided by the X Data Archive download — into usernames, since that file only contains user IDs.
- Python 3.6 or higher
- Chrome browser
- ChromeDriver
Install the required Python packages using pip:
pip install -r requirements.txtCopy example.config.yml and replace username, password, & account_name with your X account credentials. Below is an example configuration:
x_credentials:
username: "username_here" # Your X login username
password: "pass_here" # Your X login password
account_name: "username_here" # Your X account name (for getting followers)
message: "Hey follower! Please follow our primary/main account at @PrimaryAccount\n\nWe had to switch accounts, so would greatly appreciate if you followed the other. You can unfollow this one after too, if you prefer it."
headless: true # Set to false if you want to see the browser
# Advanced options
options:
dm_interval: 10 # Seconds between DMs
retry_failed: true # Retry failed DMs once
max_followers_to_process: 2500 # Limit number of followers to process
skip_first_n: 0 # Skip the first N followers (useful to resume after errors)
take_screenshots: true # Enable or disable taking screenshots throughout steps
useFollowerstxt: false # When true, uses followers.txt (which can be generated from X-ID2Username tool). When false, it scrolls the account's followers list- Load Configuration: Reads the configuration from
config.yml. - Initialize WebDriver: Sets up the Chrome WebDriver with the specified options.
- Login: Logs into your X account using the provided credentials.
- Fetch Followers: Retrieves a list of your followers. (Unless using followers.txt)
- Send DMs: Sends a predefined message to each follower.
- Save Progress: Tracks progress to avoid messaging the same follower more than once.
- Verify Message: Verifies the message by checking the first few words of the predefined message in the DM.
- Set Up Configuration: Ensure the
config.ymlfile is correctly configured with your X credentials and message. - Run the Script: Execute the script using Python.
python main.pyThe script logs its activities to a file named x_dm_script_<timestamp>.log and also outputs to the console. This log file is useful for debugging and tracking the script's progress.
If the take_screenshots option is enabled, the script will save screenshots at various stages, such as login errors, profile views, and after sending DMs. These screenshots are saved in the root directory of the project with descriptive filenames. You will want to set this to false after any debugging and it's working correctly, otherwise these images will take up a lot of space.
- ChromeDriver Errors: Ensure that ChromeDriver is installed and the version matches your Chrome browser version.
- Login Issues: Check the log file for errors during login. Ensure your credentials are correct.
- Rate Limiting: If you encounter rate limiting, increase the
dm_intervalin the configuration file. - DM Limits: X has a DM limit for non-premium accounts. Once this limit is reached, with this current version of the code, it's very possible the app will think it's successfully sending DMs when it's really not.
Using followers.txt from X-ID2Username
For accounts with 1,000 or more followers, scrolling through the followers list (x.com/username/followers) eventually stops loading more users.
To work around this, use the X-ID2Username tool. It takes the follower.js file from the account's X Data Archive download and converts it to JSON. Then, using a (headless) browser, it visits each user link — which only contain user IDs — and extracts their usernames into a followers.txt file.
This DM tool can then be configured to send messages using that list.
To enable this behavior, just set useFollowerstxt to true in your config.yml file.
Feel free to fork this project and submit pull requests.
- If a follower has sent you a DM, and you haven't accepted the message, it will fail to send that user a DM.
- Regarding this error, "WARNING - Error checking input content: Message: stale element reference: stale element not found in the current frame", it may happen frequently, and while the DM might not be verified but it does send the message.
- Fix pre-verification before sending DM, so it checks to see if the message in
config.ymlhas already been sent to the user. This would be ideal in scenerios wheremessaged_followers.jsonis removed/lost, as well any users added to it that weren't actually sent a DM. (Current logic doesn't work well)
This project is licensed under the MIT License.
slapped together by rich