Automation Modules: Browsing & Stories
Relevant source files
The following files were used as context for generating this wiki page:
Automation modules within the bot-auto-ig project provide the core logic for simulating human-like interactions on Instagram. These modules handle complex navigation, content consumption (browsing feeds and watching stories), and relationship data extraction (scraping followers/following). They are designed to operate within a workflow execution environment, utilizing randomized delays and configurable behavior to mimic authentic user sessions.
The system is structured around "activities" that can be scheduled and executed as part of a larger workflow. Key functionalities include feed browsing with integrated story viewing, automated scrolling with randomized parameters, and robust scrapers for relationship data that handle pagination and rate limiting.
Browsing and Feed Interaction
The browsing module is responsible for navigating the main feed and simulating content consumption. This is primarily handled by the browse_feed activity, which integrates post viewing with optional story interaction.
Feed Consumption Logic
The browse_feed activity utilizes specialized configuration to determine how it interacts with the feed. It includes parameters for skipping posts, viewing duration, and whether to interleave story watching with feed scrolling.
| Parameter | Type | Default | Description |
|---|---|---|---|
watch_stories | boolean | false | Whether to watch stories while browsing the feed. |
stories_min_view_seconds | number | 2 | Minimum time to spend watching a single story. |
stories_max_view_seconds | number | 5 | Maximum time to spend watching a single story. |
skip_post_chance | number | 30 | Percentage chance to skip a post in the feed. |
post_view_min_seconds | number | 2 | Minimum time to view a post. |
post_view_max_seconds | number | 5 | Maximum time to view a post. |
Sources: tests/convex/workflows.test.ts:168-175
Scrolling Mechanics
Scrolling is a foundational action for feed browsing. The system uses randomized scrolling to avoid detection, adjusting the "intensity" and "distance" of each scroll move.
This diagram represents the iterative process of simulated scrolling where distances and pauses are randomized. Sources: python/actions/browsing/scrolling.py, python/actions/browsing/feed_scrolling/runtime.py
Story Interaction
The stories module allows the automation agent to consume temporary content. It can be executed as a standalone activity or triggered during a feed browsing session if watch_stories is enabled.
Story Viewing Flow
The story viewer identifies available stories from the tray and iterates through them. It respects minimum and maximum viewing durations to simulate natural consumption patterns.
Sources: python/actions/stories/stories.py, tests/convex/workflows.test.ts:171-172
Relationship Scraping and Navigation
The Relationship Scraping module is one of the most complex automation components, designed to extract lists of followers or following from target accounts. It utilizes a stateful ScrapeRelationshipsExecutor to manage long-running tasks.
Scraper Architecture
The scraper handles target profiles by navigating to their pages, identifying relationship links, and fetching data in "chunks" through in-page scripts.
The sequence above illustrates the interaction between the executor, the browser page, and the backend for state persistence. Sources: python/runners/workflow/scrape_relationships.py:73-98, python/runners/workflow/scrape_navigation.py:12-25
Key Navigation Functions
Navigation within the relationship UI relies on multiple strategies to locate and click links, ensuring robustness against UI changes.
open_relationship_view: Normalizes target usernames and attempts to open the specified relationship list (followers or following)._click_via_selector: Uses a prioritized list of CSS selectors (e.g.,a[href="/username/followers/"]) to find links._click_via_locators: A fallback strategy using Playwright locators based on ARIA roles and text labels like "Followers" or "Following"._wait_for_relationship_ui: Monitors the URL and DOM to confirm the relationship dialog has successfully opened.
Sources: python/runners/workflow/scrape_navigation.py:12-108
Scraping State and Resilience
The scraper is built to be interruptible and resumable. It maintains detailed state in the database, including:
- Cursor Tracking: Tracks pagination position in the current list.
- Resume Snapshots: Periodically saves partial results to disk or storage to prevent data loss on failure.
- Daily Limits: Monitors
daily_scraping_usedanddaily_scraping_limitper profile to prevent account flagging. - Exponential Backoff: Implements retries for transient errors using configurable delays.
Sources: python/runners/workflow/scrape_relationships.py:133-160, python/runners/workflow/scrape_relationships.py:590-620
Relationship Data Model
Scraping activities generate "Artifacts" which represent the final collected data.
| Field | Type | Description |
|---|---|---|
kind | 'followers' | 'following' | The type of relationship list scraped. |
scraped | number | Total number of users fetched from the API. |
deduped | number | Unique count of users after removing duplicates. |
targetsCompleted | number | Number of target accounts successfully processed. |
storageId | string | ID for the JSON export in storage. |
Sources: python/runners/workflow/scrape_relationships.py:488-510, server/shared/convexClient.ts:446-465
Conclusion
The browsing and stories modules, alongside the relationship scrapers, form the functional core of the automation engine. By combining randomized interaction logic (scrolling, viewing) with robust data extraction techniques (stateful execution, multi-strategy navigation, and persistent checkpointing), the system achieves a balance between automated efficiency and detection avoidance. The modular nature of these components allows them to be flexibly integrated into various workflows, as evidenced by the configuration and test suites.