Automation Modules: Messaging & DMs
Relevant source files
The following files were used as context for generating this wiki page:
The Messaging and Direct Messaging (DM) module is a core component of the bot-auto-ig automation suite. It provides the logic for navigating Instagram profiles, composing personalized messages using templates, and managing the delivery lifecycle. This module integrates closely with the workflow system to allow scheduled and targeted outreach based on scraped data or specific user lists.
The system is designed with safety and human-emulation in mind, utilizing randomized delays for navigation, typing, and between-target transitions. It supports macro substitution (e.g., {userName}) to personalize content and includes automated fallback logic, such as following a profile if the message button is not immediately available.
Messaging Architecture and Flow
The messaging system operates through a Python-based runtime that interacts with a browser instance. The flow is managed by run_messaging_flow, which iterates through a list of targets and message templates.
Execution Workflow
The following diagram illustrates the logical flow of processing a single messaging target:
Data Components
The module relies on several data structures defined in the Convex schema and shared TypeScript clients:
- Message Templates: Arrays of strings categorized by
kind(e.g., "message"). - Instagram Accounts: Target metadata including
userName,fullName, andstatus. - Behavior Config: Parameters controlling timing and automated actions.
Sources: convex/schema.ts:51-57, server/shared/convexClient.ts:474-486
Messaging Runtime Logic
The core execution logic resides in python/actions/messaging/runtime.py. It handles the browser interaction layer, ensuring that actions appear natural and respect configured limits.
Macro Substitution and Typing
Messages are personalized using a macro system. The _type_message function replaces placeholders with actual target data before simulating keystrokes with randomized intervals.
| Macro | Description |
|---|---|
{userName} | The Instagram handle of the target. |
{fullName} | The full name displayed on the target's profile. |
{matchedName} | A name matched through filtration or keyword lists. |
Sources: python/actions/messaging/runtime.py:44-53
Behavior Configuration
The messaging behavior is highly configurable, allowing fine-tuning of delays to avoid detection.
| Parameter | Type | Default | Description |
|---|---|---|---|
navigation_delay_range | float (sec) | 2.0 - 3.0 | Delay after navigating to a profile. |
composer_delay_range | float (sec) | 1.0 - 2.0 | Delay while the message box is open. |
typing_delay_range_ms | int (ms) | 100 - 200 | Delay between individual keystrokes. |
follow_if_missing | boolean | True | Whether to follow a user to unlock DMs. |
Sources: python/actions/messaging/runtime.py:107-133, tests/convex/workflows.test.ts:153-158
Integration and Communication
The messaging module is integrated into the broader system through Express API routes and WebSocket broadcasts. This allows the frontend to monitor progress in real-time.
Messaging Sequence Diagram
This diagram shows the communication between the Server, the Python Runtime, and the Database (Convex) during a messaging task:
API Endpoints for Messaging Management
The system provides endpoints to manage templates and trigger automation:
GET /api/message-templates?kind={kind}: Retrieves templates for a specific category.POST /api/message-templates: Upserts a list of message strings for a given kind.POST /api/automation/start: Initiates the automation runner which includes messaging flows.
Sources: server/shared/convexClient.ts:474-486, server/automation/routes.ts:37-53
Status and State Management
Messaging tasks update the instagramAccounts table to track progress and prevent duplicate messaging.
Account Status Transitions
When a message is sent or a "Follow" action is taken to unlock messaging, the account status is updated:
- Subscribed: Set if the bot successfully follows a target to enable the message button.
- Custom Success Status: If configured in
direct_message_success_status, the account is updated to this status (e.g., "contacted") after a successful send. - Last Messaged At: A timestamp is recorded in the database to ensure cooldowns are respected.
Sources: python/actions/messaging/runtime.py:165-195, convex/schema.ts:39-50
Summary
The Messaging & DM module provides a robust, human-emulating framework for automated Instagram outreach. By combining customizable message templates, randomized behavioral delays, and tight integration with the Convex database for state tracking, it ensures efficient and safe communication within the bot-auto-ig ecosystem.