{"id":27111940,"url":"https://github.com/just-rich/x-dm-followers","last_synced_at":"2025-10-10T14:12:53.863Z","repository":{"id":287667135,"uuid":"965446990","full_name":"just-rich/X-DM-Followers","owner":"just-rich","description":"Python script that sends a DM to all the users that follow the account. With headless browser option and detailed debugging logs.","archived":false,"fork":false,"pushed_at":"2025-04-13T07:22:39.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T08:12:42.794Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/just-rich.png","metadata":{},"created_at":"2025-04-13T07:22:39.000Z","updated_at":"2025-04-13T07:22:39.000Z","dependencies_parsed_at":"2025-04-13T08:12:38.590Z","dependency_job_id":"e7dfba82-953f-461a-b21a-62aa11dc84d6","html_url":"https://github.com/just-rich/X-DM-Followers","commit_stats":null,"previous_names":["just-rich/x-dm-followers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/just-rich/X-DM-Followers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just-rich%2FX-DM-Followers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just-rich%2FX-DM-Followers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just-rich%2FX-DM-Followers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just-rich%2FX-DM-Followers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/just-rich","download_url":"https://codeload.github.com/just-rich/X-DM-Followers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just-rich%2FX-DM-Followers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004181,"owners_count":26083688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["direct-message","direct-messaging","dm","headless","headless-browser","messager","messaging","python","selenium","selenium-webdriver","twitter","twitter-dm","twitter-dm-tool","twitter-dmer","twitter-dmer-tool","x","x-dm","x-dm-tool","x-dmer","x-dmer-tool"],"created_at":"2025-04-07T01:25:25.085Z","updated_at":"2025-10-10T14:12:53.859Z","avatar_url":"https://github.com/just-rich.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# X DM Followers\n**Warning: This script may breach X's Terms of Service contract that you agreed to when creating an account. It was made for educational \u0026 informational purposes.**\n\nThis 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 does NOT use the X API, as their free tier does not include sending DMs. It uses a web browser to login, list followers, \u0026 send DMs to these users.**\n\n## Features\n\n- **Headless Browser**: Uses Selenium with a headless Chrome browser for automation.\n- **Configurable**: Allows customization of DM intervals, retry attempts, maximum followers to process, and more via a config file.\n- **Progress Tracking**: Saves progress to avoid messaging the same follower more than once.\n- **Screenshot Option**: Can take screenshots at various stages for debugging purposes.\n- **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)*\n\n## Requirements\n\n- Python 3.6 or higher\n- Chrome browser\n- ChromeDriver\n\n## Dependencies\n\nInstall the required Python packages using `pip`:\n\n```bash\npython -m pip install requirements.txt\n```\n\n## Configuration\n\nCopy `example.config.yml` and replace *username*, *password*, \u0026 *account_name* with your X account credentials. Below is an example configuration:\n\n```yaml\nx_credentials:\n  username: \"username_here\"  # Your X login username\n  password: \"pass_here\"  # Your X login password\n  account_name: \"username_here\"  # Your X account name (for getting followers)\n\nmessage: \"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.\"\n\nheadless: true  # Set to false if you want to see the browser\n\n# Advanced options\noptions:\n  dm_interval: 10  # Seconds between DMs\n  retry_failed: true  # Retry failed DMs once\n  max_followers_to_process: 2500  # Limit number of followers to process\n  skip_first_n: 0  # Skip the first N followers (useful to resume after errors)\n  take_screenshots: true  # Enable or disable taking screenshots\n```\n\n## How It Works\n\n1. **Load Configuration**: Reads the configuration from `config.yml`.\n2. **Initialize WebDriver**: Sets up the Chrome WebDriver with the specified options.\n3. **Login**: Logs into your X account using the provided credentials.\n4. **Fetch Followers**: Retrieves a list of your followers.\n5. **Send DMs**: Sends a predefined message to each follower.\n6. **Save Progress**: Tracks progress to avoid messaging the same follower more than once.\n7. **Verify Message**: Verifies the message by checking the first few words of the predefined message in the DM.\n\n## Usage\n\n1. **Set Up Configuration**: Ensure the `config.yml` file is correctly configured with your X credentials and message.\n2. **Run the Script**: Execute the script using Python.\n\n```bash\npython main.py\n```\n\n## Logging\n\nThe script logs its activities to a file named `x_dm_script_\u003ctimestamp\u003e.log` and also outputs to the console. This log file is useful for debugging and tracking the script's progress.\n\n## Screenshots\n\nIf 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.**\n\n## Troubleshooting\n\n- **ChromeDriver Errors**: Ensure that ChromeDriver is installed and the version matches your Chrome browser version.\n- **Login Issues**: Check the log file for errors during login. Ensure your credentials are correct.\n- **Rate Limiting**: If you encounter rate limiting, increase the `dm_interval` in the configuration file.\n- **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.\n\n## Contributing\n\nFeel free to fork this project and submit pull requests.\n\n## To Do / Notes\n- Add support for importing a [downloaded X data archive](https://x.com/settings/download_your_data), extracting follower usernames or profile links, and sending DMs to users from the generated list\n- If a follower has sent you a DM and you haven't accepted the message, it will fail to send that user a DM.\n- Regarding this error, \"WARNING - Error checking input content: Message: stale element reference: stale element not found in the current frame\", it may happen requently and the DM might not be verified but it does send the message.\n- Add pre-verification, so before sending DM it checks to see if that message has already been sent to the user. This would be ideal in scenerios where `messaged_followers.json` is removed/lost, as well any users added to it that weren't actually sent a DM.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n### Author\n\nslapped together by [rich](https://richw.xyz)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjust-rich%2Fx-dm-followers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjust-rich%2Fx-dm-followers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjust-rich%2Fx-dm-followers/lists"}