0
# Bot Automation
1

2
High-level Instagram automation framework with built-in safety features, rate limiting, intelligent filtering, and batch operations. The Bot class provides comprehensive automation capabilities while maintaining account security through configurable limits and smart filtering.
3

4
## Capabilities
5

6
### Bot Initialization and Authentication
7

8
Initialize and configure the Instagram bot with extensive customization options for safety, rate limiting, and behavior modification.
9

10
```python { .api }
11
class Bot:
12
    def __init__(self,
13
                 base_path=current_path + "/config/",
14
                 whitelist_file="whitelist.txt",
15
                 blacklist_file="blacklist.txt",
16
                 comments_file="comments.txt",
17
                 followed_file="followed.txt",
18
                 unfollowed_file="unfollowed.txt",
19
                 skipped_file="skipped.txt",
20
                 friends_file="friends.txt",
21
                 proxy=None,
22
                 max_likes_per_day=random.randint(50, 100),
23
                 max_unlikes_per_day=random.randint(50, 100),
24
                 max_follows_per_day=random.randint(50, 100),
25
                 max_unfollows_per_day=random.randint(50, 100),
26
                 max_comments_per_day=random.randint(50, 100),
27
                 max_blocks_per_day=random.randint(50, 100),
28
                 max_unblocks_per_day=random.randint(50, 100),
29
                 max_likes_to_like=random.randint(50, 100),
30
                 min_likes_to_like=random.randint(50, 100),
31
                 max_messages_per_day=random.randint(50, 100),
32
                 filter_users=False,
33
                 filter_private_users=False,
34
                 filter_users_without_profile_photo=False,
35
                 filter_previously_followed=False,
36
                 filter_business_accounts=False,
37
                 filter_verified_accounts=False,
38
                 max_followers_to_follow=5000,
39
                 min_followers_to_follow=10,
40
                 max_following_to_follow=2000,
41
                 min_following_to_follow=10,
42
                 max_followers_to_following_ratio=15,
43
                 max_following_to_followers_ratio=15,
44
                 min_media_count_to_follow=3,
45
                 max_following_to_block=2000,
46
                 like_delay=random.randint(300, 600),
47
                 unlike_delay=random.randint(300, 600),
48
                 follow_delay=random.randint(300, 600),
49
                 unfollow_delay=random.randint(300, 600),
50
                 comment_delay=random.randint(300, 600),
51
                 block_delay=random.randint(300, 600),
52
                 unblock_delay=random.randint(300, 600),
53
                 message_delay=random.randint(300, 600),
54
                 stop_words=("shop", "store", "free"),
55
                 blacklist_hashtags=["#shop", "#store", "#free"],
56
                 blocked_actions_protection=True,
57
                 blocked_actions_sleep=True,
58
                 blocked_actions_sleep_delay=random.randint(600, 1200),
59
                 verbosity=True,
60
                 device=None,
61
                 save_logfile=True,
62
                 log_filename=None,
63
                 loglevel_file=logging.DEBUG,
64
                 loglevel_stream=logging.INFO,
65
                 log_follow_unfollow=True):
66
        """
67
        Initialize Instagram bot with comprehensive configuration options.
68
        
69
        Parameters:
70
        - base_path: Directory for bot configuration files (current_path + "/config/")
71
        - whitelist_file, blacklist_file, comments_file, followed_file, unfollowed_file, 
72
          skipped_file, friends_file: Filenames for various user lists and bot state
73
        - proxy: Proxy server configuration
74
        - max_*_per_day: Daily limits for actions (random.randint(50, 100))
75
        - max_likes_to_like, min_likes_to_like: Like count filtering thresholds
76
        - max_messages_per_day: Daily message limit
77
        - filter_*: Boolean flags for user filtering (defaults False)
78
        - max/min_followers/following_to_follow: Follower/following count thresholds
79
        - max_followers_to_following_ratio, max_following_to_followers_ratio: Ratio limits
80
        - min_media_count_to_follow: Minimum media posts required
81
        - max_following_to_block: Maximum following count for blocking
82
        - *_delay: Action delays in seconds (random.randint(300, 600) or (600, 1200))
83
        - stop_words: Tuple of words to avoid in usernames/bios
84
        - blacklist_hashtags: List of hashtags to avoid
85
        - blocked_actions_protection, blocked_actions_sleep: Safety features
86
        - verbosity: Enable verbose logging
87
        - device, save_logfile, log_filename, loglevel_*: API configuration
88
        - log_follow_unfollow: Log follow/unfollow actions
89
        """
90

91
    def login(self, username=None, password=None, **args):
92
        """
93
        Login to Instagram with bot configuration and safety checks.
94
        
95
        Parameters:
96
        - username: Instagram username
97
        - password: Instagram password
98
        - **args: Additional login parameters passed to API
99
        
100
        Returns:
101
        bool: True if login successful, False otherwise
102
        """
103

104
    def logout(self):
105
        """
106
        Logout from Instagram and display session statistics.
107
        
108
        Prints comprehensive statistics about bot actions performed
109
        during the session including likes, follows, comments, etc.
110
        """
111
```
112

113
### Content Upload and Management
114

115
Upload and manage photos and videos with automatic filtering and safety checks.
116

117
```python { .api }
118
def upload_photo(self, photo, caption=None, upload_id=None, from_video=False, options={}):
119
    """
120
    Upload photo to Instagram with bot validation and logging.
121
    
122
    Parameters:
123
    - photo: Path to photo file or photo data
124
    - caption: Photo caption text
125
    - upload_id: Optional upload identifier
126
    - from_video: Whether photo is extracted from video
127
    - options: Additional upload options
128
    
129
    Returns:
130
    bool: True if upload successful, False otherwise
131
    """
132

133
def upload_video(self, video, caption="", thumbnail=None, options={}):
134
    """
135
    Upload video to Instagram with thumbnail and caption.
136
    
137
    Parameters:
138
    - video: Path to video file
139
    - caption: Video caption text
140
    - thumbnail: Path to thumbnail image
141
    - options: Additional upload options
142
    
143
    Returns:
144
    bool: True if upload successful, False otherwise
145
    """
146

147
def download_photo(self, media_id, folder="photos", filename=None, save_description=False):
148
    """
149
    Download photo from Instagram by media ID.
150
    
151
    Parameters:
152
    - media_id: Instagram media identifier
153
    - folder: Download destination folder
154
    - filename: Custom filename (optional)
155
    - save_description: Save caption as text file
156
    
157
    Returns:
158
    bool: True if download successful, False otherwise
159
    """
160

161
def download_video(self, media_id, folder="videos", filename=None, save_description=False):
162
    """
163
    Download video from Instagram by media ID.
164
    
165
    Parameters:
166
    - media_id: Instagram media identifier
167
    - folder: Download destination folder
168
    - filename: Custom filename (optional)
169
    - save_description: Save caption as text file
170
    
171
    Returns:
172
    bool: True if download successful, False otherwise
173
    """
174
```
175

176
### Automated Engagement Actions
177

178
Perform automated likes, follows, and other engagement actions with intelligent targeting and safety limits.
179

180
```python { .api }
181
def like_timeline(self, amount=None):
182
    """
183
    Automatically like posts from timeline feed.
184
    
185
    Parameters:
186
    - amount: Number of posts to like (uses bot limits if None)
187
    
188
    Returns:
189
    int: Number of posts successfully liked
190
    """
191

192
def like_user(self, user_id, amount=None, filtration=True):
193
    """
194
    Like posts from specific user with filtering and limits.
195
    
196
    Parameters:
197
    - user_id: Target user ID or username
198
    - amount: Number of posts to like
199
    - filtration: Apply bot filtering criteria
200
    
201
    Returns:
202
    int: Number of posts successfully liked
203
    """
204

205
def like_hashtag(self, hashtag, amount=None):
206
    """
207
    Like posts from hashtag feed with smart filtering.
208
    
209
    Parameters:
210
    - hashtag: Hashtag name (without #)
211
    - amount: Number of posts to like
212
    
213
    Returns:
214
    int: Number of posts successfully liked
215
    """
216

217
def like_followers(self, user_id, nlikes=None, nfollows=None):
218
    """
219
    Like posts from followers of target user.
220
    
221
    Parameters:
222
    - user_id: Target user ID or username
223
    - nlikes: Number of likes per follower
224
    - nfollows: Number of followers to process
225
    
226
    Returns:
227
    int: Number of users processed
228
    """
229

230
def follow_followers(self, user_id, nfollows=None):
231
    """
232
    Follow followers of target user with filtering.
233
    
234
    Parameters:
235
    - user_id: Target user ID or username
236
    - nfollows: Number of users to follow
237
    
238
    Returns:
239
    int: Number of users successfully followed
240
    """
241

242
def follow_following(self, user_id, nfollows=None):
243
    """
244
    Follow users that target user is following.
245
    
246
    Parameters:
247
    - user_id: Target user ID or username
248
    - nfollows: Number of users to follow
249
    
250
    Returns:
251
    int: Number of users successfully followed
252
    """
253

254
def unfollow_non_followers(self, n_to_unfollows=None):
255
    """
256
    Unfollow users who don't follow back.
257
    
258
    Parameters:
259
    - n_to_unfollows: Number of users to unfollow
260
    
261
    Returns:
262
    int: Number of users successfully unfollowed
263
    """
264

265
def unfollow_everyone(self):
266
    """
267
    Unfollow all currently followed users.
268
    
269
    Returns:
270
    int: Number of users successfully unfollowed
271
    """
272
```
273

274
### Content Discovery and Filtering
275

276
Discover and filter content based on sophisticated criteria for targeted automation.
277

278
```python { .api }
279
def get_hashtag_medias(self, hashtag, filteration=True):
280
    """
281
    Get media posts from hashtag with optional filtering.
282
    
283
    Parameters:
284
    - hashtag: Hashtag name (without #)
285
    - filteration: Apply bot filtering criteria
286
    
287
    Returns:
288
    list: List of media IDs that passed filtering
289
    """
290

291
def get_user_medias(self, user_id, filteration=True, is_comment=False):
292
    """
293
    Get media posts from specific user.
294
    
295
    Parameters:
296
    - user_id: Target user ID or username
297
    - filteration: Apply bot filtering criteria
298
    - is_comment: Whether media is for commenting
299
    
300
    Returns:
301
    list: List of media IDs that passed filtering
302
    """
303

304
def get_timeline_medias(self):
305
    """
306
    Get media posts from timeline feed.
307
    
308
    Returns:
309
    list: List of media IDs from timeline
310
    """
311

312
def get_popular_medias(self):
313
    """
314
    Get popular/trending media posts.
315
    
316
    Returns:
317
    list: List of popular media IDs
318
    """
319

320
def filter_medias(self, media_items, filteration=True, quiet=False, is_comment=False):
321
    """
322
    Filter media posts based on bot criteria.
323
    
324
    Parameters:
325
    - media_items: List of media items to filter
326
    - filteration: Enable filtering
327
    - quiet: Suppress logging output
328
    - is_comment: Whether filtering for commenting
329
    
330
    Returns:
331
    list: Filtered list of media items
332
    """
333

334
def check_user(self, user, unfollowing=False):
335
    """
336
    Check if user meets bot criteria for interaction.
337
    
338
    Parameters:
339
    - user: User data dictionary or user ID
340
    - unfollowing: Whether check is for unfollowing action
341
    
342
    Returns:
343
    bool: True if user passes criteria, False otherwise
344
    """
345

346
def check_media(self, media):
347
    """
348
    Check if media meets bot criteria for interaction.
349
    
350
    Parameters:
351
    - media: Media data dictionary
352
    
353
    Returns:
354
    bool: True if media passes criteria, False otherwise
355
    """
356
```
357

358
### User Management and Information
359

360
Manage user relationships and retrieve user information with caching and filtering.
361

362
```python { .api }
363
def get_user_followers(self, user_id, nfollows=None):
364
    """
365
    Get followers of specific user with limits.
366
    
367
    Parameters:
368
    - user_id: Target user ID or username
369
    - nfollows: Maximum number of followers to retrieve
370
    
371
    Returns:
372
    list: List of follower user IDs
373
    """
374

375
def get_user_following(self, user_id, nfollows=None):
376
    """
377
    Get users that specific user is following.
378
    
379
    Parameters:
380
    - user_id: Target user ID or username
381
    - nfollows: Maximum number of following to retrieve
382
    
383
    Returns:
384
    list: List of following user IDs
385
    """
386

387
def get_user_info(self, user_id, use_cache=True):
388
    """
389
    Get detailed user information with caching.
390
    
391
    Parameters:
392
    - user_id: Target user ID or username
393
    - use_cache: Use cached information if available
394
    
395
    Returns:
396
    dict: User information dictionary
397
    """
398
```
399

400
### Statistics and Analytics
401

402
Track and analyze bot performance with comprehensive statistics and reporting.
403

404
```python { .api }
405
def save_user_stats(self, username, path=""):
406
    """
407
    Save user statistics to file for analysis.
408
    
409
    Parameters:
410
    - username: Username to save stats for
411
    - path: Directory path for stats file
412
    
413
    Returns:
414
    bool: True if stats saved successfully
415
    """
416

417
def print_counters(self):
418
    """
419
    Print comprehensive statistics about bot actions.
420
    
421
    Displays counters for likes, follows, unfollows, comments,
422
    and other actions performed during the session.
423
    """
424
```
425

426
### Bot Properties
427

428
Access bot state, configuration, and collected data through properties.
429

430
```python { .api }
431
@property
432
def following(self):
433
    """List of user IDs currently being followed"""
434

435
@property 
436
def followers(self):
437
    """List of current follower user IDs"""
438

439
@property
440
def blacklist(self):
441
    """Set of blacklisted user IDs"""
442

443
@property
444
def whitelist(self):
445
    """Set of whitelisted user IDs"""
446

447
@property
448
def total(self):
449
    """Dictionary of action counters"""
450

451
@property
452
def blocked_actions(self):
453
    """Dictionary of blocked action flags"""
454
```
455

456
## Usage Examples
457

458
### Basic Automation Workflow
459

460
```python
461
from instabot import Bot
462

463
# Initialize bot with custom limits
464
bot = Bot(
465
    max_likes_per_day=80,
466
    max_follows_per_day=60,
467
    filter_private_users=True,
468
    min_followers_to_follow=100
469
)
470

471
# Login
472
bot.login(username="your_username", password="your_password")
473

474
# Upload content
475
bot.upload_photo("content/photo1.jpg", caption="Check out this amazing view! #photography #nature")
476

477
# Automated engagement
478
bot.like_hashtag("photography", amount=15)
479
bot.follow_followers("target_photographer", nfollows=10)
480

481
# Content discovery and targeted actions
482
media_ids = bot.get_hashtag_medias("landscape")
483
for media_id in media_ids[:5]:
484
    bot.like(media_id)
485

486
# Cleanup actions
487
bot.unfollow_non_followers(n_to_unfollows=20)
488

489
# View statistics and logout
490
bot.print_counters()
491
bot.logout()
492
```
493

494
### Advanced Configuration
495

496
```python
497
from instabot import Bot
498

499
# Advanced bot configuration
500
bot = Bot(
501
    base_path="./my_bot_config/",
502
    proxy="http://proxy.example.com:8080",
503
    max_likes_per_day=120,
504
    max_follows_per_day=80,
505
    filter_verified_users=False,  # Allow verified users
506
    max_followers_to_follow=10000,
507
    min_followers_to_follow=50,
508
    max_following_to_followers_ratio=1.5,
509
    min_media_count_to_follow=5
510
)
511

512
bot.login(username="advanced_user", password="secure_password")
513

514
# Multi-hashtag strategy
515
hashtags = ["python", "coding", "programming", "developer"]
516
for hashtag in hashtags:
517
    bot.like_hashtag(hashtag, amount=8)
518
    
519
# Targeted following with limits
520
influencers = ["tech_leader1", "python_expert", "coding_guru"]
521
for influencer in influencers:
522
    bot.follow_followers(influencer, nfollows=15)
523

524
bot.logout()
525
```