<p align="center">
  <img src="https://github.com/GramAddict/bot/raw/master/res/logo.png" width="250">
  <br />
  <h1 align="center">GramAddict</h1>
  <br />
  <p align="center">Looking for Instagram automation? I'm proud to present you a <b>100% free and open source Instagram bot</b>. This bot will allow you to grow your following and engagement by liking, following, commenting and sending PM automatically with your Android phone/tablet/emulator. <b>No root required.</b> <p>
  <p align="center">
    <a href="https://github.com/gramaddict/bot/blob/master/LICENSE">
      <img src="https://img.shields.io/github/license/gramaddict/bot?style=flat" />
    </a>
    <a href="https://www.python.org/">
      <img src="https://img.shields.io/badge/built%20with-Python3-red.svg?style=flat" />
    </a>
    <a href="https://github.com/GramAddict/bot/pulls">
      <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" />
    </a>
    <a href="https://github.com/GramAddict/bot/issues">
    	<img src="https://img.shields.io/github/issues/gramaddict/bot?style=flat" />
    </a>
    <a href="https://github.com/GramAddict/bot/pulls">
      <img src="https://img.shields.io/github/issues-pr/gramaddict/bot?style=flat" />
    </a>
    <a href="https://github.com/GramAddict/bot/stargazers">
	    <img src="https://img.shields.io/github/stars/gramaddict/bot?style=flat">
    </a>
    <a href="https://img.shields.io/github/last-commit/gramaddict/bot/develop?style=flat">
	    <img src="https://img.shields.io/github/last-commit/gramaddict/bot/develop?style=flat">
    </a>
    <a href="https://pypi.org/project/gramaddict/">
      <img src="https://img.shields.io/pypi/dm/gramaddict">
    </a>
    <a href="https://github.com/GramAddict/bot#backers">
	    <img src="https://img.shields.io/opencollective/backers/gramaddict?style=flat">
    </a>  
    <a href="https://discord.gg/NK8PNEFGFF">
	    <img src="https://img.shields.io/discord/771481743471017994?style=flat">
    </a>
  </p>
</p>

<br />

# Why should I automate my Instagram account?
It's very hard nowadays to grow an account. Have you ever been on the explore page? IG will show your post only to close accounts & accounts you interact most with, you will never be on the explore page. Nobody will see your beautiful photos, your super funny memes, or whatever you are posting. But now you can do something about that! With GramAddict you can __get noticed easily__, and if you really deserve it, your account will __grow super fast__!

## So, do I need to publish good content to grow?
Of course you have to! This bot will mainly help you to get the __visibility you deserve__ and which is Instagram not giving you.

## Ok but I don't know how to start this journey...
Don't worry about that now, it's not that hard to start botting with GramAddict! I tried to make it as noob-friendly as possible. In any case, if you follow the docs with all the steps provided, you will make it! You are also invited to join our community and ask for any help!

## There is a community around this project?
Yes! We are on __discord__ and we count a lot of __active users__ you can ask us whatever you want!

  <a href="https://discord.gg/NK8PNEFGFF">
    <img src="https://img.shields.io/discord/771481743471017994?style=flat">
  </a>

## I saw there're a lot of similar projects on GitHub, why should I choose this one?
You're right, there're plenty of other bot solutions. Most of them use API requests. However, you will get your account banned if you use API (1-30 days)!
There's also a very similar project to this one, yet it's not free and the dev doesn't care about the community much. They removed few lines from the core and ask you for a subscription plan in order to use those features. Furthermore, you don't even know what's the real code during execution - it's crypted. And if they are stealing something else? Who knows? I don't.
This bot is __free to use__ and __open source__, you won't get charged for few extra lines, __EVER__.
I'm focused on the community and not on finding ways how to get money out of this project. __I really care about the community__ and every dev should too. 🤗

## So this bot does not use API?
__No__ this bot is working through __adb__ and is powered by __uiautomator2__ which is a testing wrapper for Android devices. In fact, your device (or an emulator) is used for doing the botting sh*it. That's very secure compared to other botting systems around there. I also made it look as much human as possible. You can think about the bot as a __stupid__ friend using your phone and doing things for you. The example bottom is quite old but will show you what we are talking about.
<p align="center">
  <img src="https://github.com/GramAddict/bot/raw/master/res/demo.gif">
</p>

## Urra! I'll never get banned anymore with this bot!
No no no, wait! 🤦
You have to configure the bot for doing things as a human would do. Do you really spend all the day scrolling on Instagram? If yes contact a medic :P
You don't have to do so many actions or Instagram will block you. That appends even if you do that by your hands.. Have you ever added a lot of people in a row and got blocked for that action? Or spamming people with a link in PM? 
__DON'T F*CKING DO THAT__

__Be gently and anonymous and nobody will notice that you're botting, trust me__.

## Do I need a computer for running the bot?
Yes, but you can also run it [directly on your phone](https://docs.gramaddict.org/#/termux)!!

In any case, you can decide to use a physical device or an emulator (if you're under Windows I suggest you use [Memu](https://www.memuplay.com/)).
For hosting the bot you can use:
- your computer (with Windows, macOS, or Linux)
- a Raspberry (which is a cheap little pc Linux based)

## Cool! What can I do with this bot? 
There are lots of __cool features__ you can use __for free__!
- Works without rooting
- Works with both emulators and physical devices
- Can be used stand-alone (without the use of a computer)
- Includes realistic random human-like delays and actions
- Can watch stories while interacting
- Comment post with emojis and [spintax logic](https://github.com/GramAddict/docs/blob/main/configuration.md#spintax-support)
- Send PM
- Type like a human (letter by letter by faking using suggestions. For example you won't type `H - e - l - l - o` letter by letter but something like `H - He - Hello`)
- Browse carousels and watch their contents
- Watch videos for a specific amount of time
- Scheduler
- Getting tasty telegram reports
- Supports multiple actions in one session
- Lots of customizable limits to keep your account safe from soft bans
- Available interactions
    - interact with a user's followers or following
    - interact with a top or recent hashtag's post likers
    - interact with a top or recent hashtag post
    - interact with a top or recent place's post likers
    - interact with a top or recent place post
    - interact with user's post likers
    - interact with a single blogger
    - interact with your feed
    - interact with users from a list (*.txt)
    - interact with posts from links inside a list (*.txt)
    - unfollow any followers
    - unfollow any followers, followed by bot
    - unfollow any followers, followed by bot, who don't follow you back
    - unfollow from a list (*.txt)
    - scrape mode for collecting usernames instead of interacting with them (you will find more information about that in the doc)

- Lots of available filters to customize who you interact with
    - you can blacklist people to avoid interacting with them
    - you can whitelist people to not remove them when you unfollow people
    - biography main characters and language
    - profile name main characters
    - private / public / business / non business account
    - number of posts / followers / following
    ... and more!
<br />

Full documentation available on [docs.gramaddict.org](https://docs.gramaddict.org)

## Telegram reports? What's that?
You can get __reports__ through telegram from your bot activities!
[Follow this guide to accomplish that](https://docs.gramaddict.org/#/configuration?id=telegram-reports).

<img src="https://github.com/GramAddict/bot/raw/master/res/telegram-reports.png" width="200">

> In this case trends are negative because I use this account only for tuning this bot and it's private...
> I didn't accept anyone lately so the trends are meh :P

Cool, isn't it? 💦
# Quick start
Now that you're there you still don't know how to install that whole thing.
I'll try to help you accomplish that with a short tutorial. The full is available [here](https://docs.gramaddict.org/#/quickstart).

## What do you need:
- a computer (with Windows, macOS or Linux)
- Python installed on your machine (with pip)
- Adb tools
- a physical device or an emulator (with Android 4.4+)
### Step 1: Install Python (>=3.6):
>Python 3.10 is currently not supported!

If you're on Linux or macOS you should have Python and Git installed, just check that your Python version is >= 3.6.

On windows you have to [install it](https://www.python.org/downloads/release/python-397/) for sure.

Failed? [Detailed tutorial here](https://docs.gramaddict.org/#/quickstart?id=step-1-install-python-if-not-installed).
>A little reminder: we refer to python with __python3__. You may have also have python2 installed if you're on Linux for example. If you're on Windows you can use __python__ instead of python3.
>Check which python alias you have to use by typing `python -V` or `python3 -V` or `py -V` and use the right one for the rest of the tutorial.

>Check that pip3 is installed by typing `pip3 -V`
>If that returns an error you have to install it! How? [Google is your best friend!](https://www.google.com/search?q=how+to+install+pip) :P
### Step 2: Install GramAddict:
You can install GramAddict in two ways: with __pip__ or with __git__.
Is good practice to create virtual environments when you install a new package. That will save you from a lot of problems!

#### Create a virtual environment
We create a virtual environment called `.venv` and activate it:

- create a directory where you will create the new environment
- write in console: `python3 -m venv .venv`
  > We use `venv` instead of `virtualenv` because `venv` is shipped directly with python3 and you don't have to install anything 🤪
- activate the .venv:
    - `source .venv/bin/activate` on Linux/macOS
    - `.venv\Scripts\activate.bat` on Windows cmd
    - `.venv\Scripts\activate.ps1` on Windows PowerShell
      > If you activate the venv correctly, you will see a little (.venv) on the left side of the command line!
#### With pip (I suggest you this way):

- install the package: `pip3 install GramAddict`
- check if it's installed: `gramaddict --version`
- if everything is fine you will get the GramAddict version installed 🥳

#### With git:
> __Warning:__ console commands like `gramaddict init`, `gramaddict dump` and `gramaddict run` won't work if you installed the bot with git.
- clone the project: `git clone https://github.com/GramAddict/bot.git gramaddict`
- enter the gramaddict folder: `cd gramaddict`
- install the requirements: `pip3 install -r requirements.txt`

### Step 3: Install adb:
Adb stands for [Android Debug Bridge](https://developer.android.com/studio/command-line/adb). It's needed for making this bot working properly. I think this one is the hardest part to accomplish but don't give up! You can do it, with my help. 💪
1. download [this package](https://developer.android.com/studio/releases/platform-tools) and unzip it somewhere and remind the path
   > __Warning:__ place that where you're sure you won't ever delete it, otherwise the bot won't work anymore!
2. add platform-tools path to the PATH environment variable
   - if you're on __Linux/macOS__ that's pretty easy:
      - open ~/.bash_profile with any text editor you like
      - add the following line with the full path to the platform-tools directory: export PATH=~/Library/Android/sdk/platform-tools/:$PATH. This path may be different depending on the way you installed platform-tools
      - save file and restart Terminal
   - on __Windows__ there are more steps to accomplish that:
      - open Windows Explorer (you can press WINKEY+E) and right-click "My Computer" on left side
      - in the pop-up menu, click `Properties`
      - in the `System Properties` window, click the `Advanced` tab, and then click `Environment Variables`
      - in the `System Variables` window, highlight `Path`, and click `Edit`
      - in the `Edit System Variables` window, press on `New`
      - enter the full path for the folder platform-tools you unzipped before
      - press all the Ok and restart Command Prompt
3. check that everything is fine
   - write `adb version`, you should get something like that:
      > C:\Users\dedil>adb version
      > Android Debug Bridge version 1.0.41
      > Version 30.0.5-6877874

### Step 4: Start the bot:
This bot works only if your Instagram is in [English](https://help.instagram.com/111923612310997).
1. First thing you have to do is to [enable developer options and USB debugging](https://developer.android.com/studio/debug/dev-options#enable).
2. connect your phone to your computer with an USB cable
3. device will ask you to allow connection. Press "Connect"
4. type `adb devices` in terminal
   - a list of devices attached should be displayed, if not you did something wrong
      > List of devices attached
      > A0B1CD2345678901    device

   - this is your device ID, you have to use it only if you have more then one device connected at the same time
5. initialize uiautomator2: `uiautomator2 init`
6. initialize GramAddict: `gramaddict init your_ig_account_name_here`
    > __Warning:__ works only if you installed the bot with pip, if you used git you have to create account folder and youraccountname folder manually.
    - that script will crate all the files you need for configure and start this bot
    - you will find them inside the folder `accounts/youraccountname/`
      ```sh
        gramaddict/
          run.py
          accounts/
            youraccountname/
              config.yml
              telegram.yml
              filters.yml
              whitelist.txt
              blacklist.txt
              comments_list.txt
              pm_list.txt
      ```
7. now that you have all the requirements you have to configure the whole thing by [following this guide](https://docs.gramaddict.org/#/configuration)
8. now you're done and you can finally start the bot: `python3 run.py --config accounts/yourusername/config.yml` or `gramaddict run --config accounts/yourusername/config.yml`

Failed? [Check this out!](https://docs.gramaddict.org/#/quickstart?id=troubleshooting)

# Bot crashes, what should I do?
The script isn't perfect and may fail sometimes. If this is the case you can open a ticket on our [discord channel](https://discord.gg/NK8PNEFGFF). In that way you won't share with anyone your Instagram account name 😈. We'll be very happy to help you!

# WOW! You dedicated so much time to this project! Why you did that for free??
Well, we used to be in three a long time ago but suddenly my two friends left. This has been an opportunity for me to improve my skills in Python and that's why I didn't leave the project and keep maintaining it.
But of course donations are very welcome, so if you think I did a great job you can buy me a beer :)


<a  href="https://www.buymeacoffee.com/mastrolube"  target="_blank"><img  src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png"  hspace="10" alt="Buy Me A Coffee"  style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;"  ></a>

# Can I do something to make this project grown?
On Github there is a `star system` which indicates how good a project is. If you like this project it will be amazing if you can press the little star at the top! ⭐
# Contributors

This project exists thanks to all of our Contributors [[Contribute](https://docs.gramaddict.org/#/contributing)].

<a href="https://github.com/gramaddict/bot/graphs/contributors"><img src="https://opencollective.com/gramaddict/contributors.svg?width=890&button=false" /></a>

<br />

# Backers

Thank you to everyone that supports us financially! 🙏 [[Become a backer](https://opencollective.com/gramaddict#backer)]

<a href="https://opencollective.com/gramaddict#backers" target="_blank"><img src="https://opencollective.com/gramaddict/backers.svg?width=890"></a>
<br />

# Talk botty with us

<p>
  <a href="https://discord.gg/NK8PNEFGFF">
    <img hspace="3" alt="Join us on Discord" src="https://github.com/GramAddict/bot/raw/master/res/discord.png" height=84/>
  </a>
</p>

---

> **Disclaimer**<a name="disclaimer" />: This project comes with no guarantee or warranty. You are responsible for whatever happens from using this project. It is possible to get soft or hard banned by using this project if you are not careful.
