1. How SocialConductor.AI Works
SocialConductor.AI connects your Facebook Pages to Google's Gemini AI model to provide real-time, context-aware automated engagement β on public comments and Messenger DMs β 24/7.
End-to-End Flow
Facebook sends a webhook event
6 security gates filter
Read post + 8 recent comments
Gemini writes a reply
15β60s human-like pause
Reply posted via Graph API
Key Concepts
| Concept | What It Means |
|---|---|
| Tenant / Page | Each Facebook Page you connect is a "Tenant" with its own AI prompt, schedule, and usage limits. |
| System Prompt | The AI's personality script. Defines tone, rules, and topics for your specific business. |
| Simulation Mode | AI generates and saves draft replies to Logs β but does NOT post publicly. Safe for testing. |
| Leads Vault | Comments received outside business hours are saved and auto-processed when the schedule reopens. |
| Social Listening | The AI reads the original post and recent comments to understand conversation context. |
| Activity Log | A full record of every comment and AI response, searchable and exportable. |
2. Trial Period & Subscription Plans
Your 14-Day Free Trial
Every new account starts with a 14-day free trial β no credit card required. Here is exactly what happens at each stage:
| Period | Status | What Works |
|---|---|---|
| Days 0β13 | π Trial Active | Full access β live AI replies, both channels, all features at Free plan limits. |
| Days 14β30 | β οΈ Simulation Only | AI generates log entries but does NOT post publicly. No plan upgrade = simulation mode forced ON. |
| Day 31+ | π΄ Polling Disabled | All webhook polling is stopped. Messenger and Comments are disabled until a paid plan is activated. |
| Any time | π³ Paid Plan Active | Full unrestricted access based on your chosen plan tier (Basic / Enhanced / Enterprise). |
Subscription Plans
5 image uploads
Basic analytics
10 image uploads
Full analytics
15 image uploads
Advanced features
30 image uploads
Priority support
Plans are per-page per-month. Select pages using checkboxes on the Dashboard and use PayPal checkout. Hard daily safety cap: 1,000 replies per page, regardless of plan β this protects your account from Facebook velocity bans.
3. Setup Wizard
New users are automatically redirected to the 5-step Setup Wizard after their first Facebook login. You can re-run it at any time from the sidebar.
| Step | What You Do | Why It Matters |
|---|---|---|
| 1 β Accept Terms | Review and accept the EULA & Privacy Policy | Required for GDPR compliance and to enable live posting |
| 2 β System Prompt | Write or auto-generate your AI's personality | Controls every reply the AI will ever make |
| 3 β Operating Hours | Set active days and hours | Ensures AI only responds during business hours; Vault captures off-hours leads |
| 4 β Enable Channels | Toggle Comments and/or Messenger | Choose which interactions the AI handles |
| 5 β Analytics Tour | Learn to read Stats and Logs | Understand your data for informed decisions |
4. The System Prompt
The system prompt is the most important setting in the app. It defines who your AI is and how it speaks. The AI reads this prompt before every single reply β it is never visible to your customers.
What to Include
- Business identity: Your business name, industry, and what you sell or do.
- Tone of voice: Friendly, professional, concise, enthusiastic, formal, etc.
- Key information: Hours, location, contact details, website URL.
- Response rules: "Always end with our phone number" or "Never discuss competitor pricing".
- Call to action: "When someone asks about orders, direct them to example.com/order".
- Length limit: "Keep all responses under 2 sentences" or "Use bullet points for FAQs".
Example Prompts
π Restaurant Example
You are "Mario's Trattoria Assistant", a warm and welcoming helper for our Italian restaurant in Chicago. We serve authentic pasta, pizza, and seafood. Our hours are MonβSat 11amβ10pm, Sun 12pmβ8pm. For reservations, always mention our website (www.mariostrattoria.com) or phone (312-555-0199). When customers ask about specials, mention that our chef posts daily specials on our Facebook page. Keep responses under 3 sentences and always end with "Buon appetito! π"
π Beauty Salon Example
You are the AI assistant for "Glow Studio" β a boutique hair and nail salon in Austin, TX. You are friendly, upbeat, and conversational. Our services include haircuts, coloring, manicures, and facials starting at $35. For bookings use our online scheduler at glowstudio.com/book. If asked about pricing, always say prices "start from" rather than quoting exact totals. Never promise specific appointment times β always direct people to book online. End every reply with a beauty-related emoji.
ποΈ Fitness Studio Example
You are the virtual assistant for "IronCore Gym". You are motivational, direct, and energetic. We offer personal training, group classes (HIIT, yoga, spin), and open gym 24/7. Monthly memberships start at $29. For new member inquiries, direct them to our "Free 7-Day Pass" offer at ironcoregym.com/trial. When someone asks about classes, tell them our schedule is posted every Monday. If someone mentions an injury or medical concern, always recommend they consult a doctor first. Keep responses to 2β3 sentences max.
5. Operating Schedule
The schedule controls when the AI processes incoming comments. This is critical for businesses that want to maintain a "human feel" β a comment at 3am getting an instant reply can feel unnatural.
Schedule Modes
| Mode | Behavior | Best For |
|---|---|---|
| Fixed | Replies only within your exact set hours (e.g., 9amβ5pm) | B2B companies, law firms, medical offices |
| Random / Intermittent | Replies within your set hours but adds Β±30 minute variance to response timing | Restaurants, retail, any brand wanting natural human-like behavior |
| Disabled | AI replies 24/7 with no schedule restriction | E-commerce, global brands, 24/7 support pages |
The Leads Vault
When a comment arrives outside your schedule, it is saved to the Leads Vault (log type: vault_captured). The recovery worker (runs every 20 minutes) checks if your schedule has reopened and automatically processes any vaulted comments β so no lead is ever permanently lost.
6. Channels: Comments & Messenger
Comment Reply
When enabled, the AI monitors your Facebook Page's public posts for new comments and replies automatically. The AI reads the full thread context (original post + recent comments) before generating a response.
- Reply Threading: The AI can have multi-turn conversations. If a user replies to your AI's comment, the bot will continue the conversation thread.
- Self-Reply Protection: The AI will never reply to comments made by your own Page admin account.
- Conversation Detection: If a user continues a conversation (replying to the AI), the 60-minute deduplication window is bypassed to allow natural back-and-forth.
Messenger Reply
When enabled, the AI handles incoming Messenger DMs. It also captures:
- Postbacks / Button Clicks: Logged when users tap buttons on your Page's quick replies.
- Read Receipts: Logged when users read AI-sent messages (visible in Logs as
message_read).
pages_messaging permission and the Page to be live (not in Development mode).
7. Simulation Mode
Simulation Mode is a critical safety feature. When enabled, the full AI pipeline runs β comment detected, prompt processed, response generated β but the reply is saved to your Logs only and never posted to Facebook.
When to Use Simulation Mode
- When you first set up a new page and want to test your prompt.
- After making major changes to your system prompt.
- Before a product launch or campaign, to preview AI replies.
- If you have concerns about a specific type of comment (test with a friend's account).
Publishing Simulated Replies
In the Logs view, simulation entries have a π Post Now button. Click it to manually publish the AI's draft reply to Facebook β giving you editorial control over each response.
8. Media Manager
The Media Manager (/images) is your image library and social publishing scheduler. It integrates directly with the Facebook Graph API to post images to your Pages.
Upload & AI Caption
When you upload an image, the system sends it to Gemini Vision. Within seconds you receive 3 ready-to-post captions:
- π Funny β Casual, lighthearted tone with humor
- π Professional β Formal, brand-focused copy with hashtags
- π₯ Viral β High-energy caption optimized for engagement
Visual Editor
Click π¨ Edit Image to open the in-browser image editor. Features include: crop, resize, rotate, flip, apply filters (brightness, contrast, blur), add text overlays, and draw annotations. Edits are saved as a new copy β the original is preserved.
Scheduling
Select images using checkboxes, then use the bulk action bar to:
- Schedule to Specific Date: Choose exact date/time for publication.
- Random Future: System picks a random time in the near future to spread posts naturally.
- Post Now: Immediately publish to the selected Page.
The scheduler runs every 5 minutes. Published posts show a π View button linking directly to Facebook.
Storage Limits
| Plan | Daily Uploads | Storage |
|---|---|---|
| Free | 5 images/day | 50MB total |
| Basic | 10 images/day | 50MB total |
| Enhanced | 15 images/day | 50MB total |
| Enterprise | 30 images/day | 50MB total |
9. The 6 Safety Gates
Every incoming comment or message must pass through 6 sequential gates before the AI will respond. If any gate fails, the event is silently dropped. This protects your account and controls costs.
Compares the commenter's name to your Page name. If they match, the event is dropped immediately to prevent infinite reply loops (e.g., your own admin account commenting).
Checks if this specific comment ID has already been processed. If it has (e.g., from a duplicate webhook delivery), the event is dropped. This is critical for preventing duplicate replies.
Scans the last 60 minutes of activity logs for this user on this page. If we already replied to them recently, we skip it. Exception: if the user is continuing a conversation (replying to our comment), this gate is bypassed to allow natural back-and-forth.
If a comment is fewer than 4 words (e.g., "Cool!", "π", "Nice"), the AI skips it. Short reactions don't warrant a business reply and consuming AI credits on them would be wasteful.
To prevent your page from looking like an obvious bot, we randomly skip 20% of eligible comments. This random rate is combined with the 15β60 second typing delay to create a realistic, human-like engagement pattern.
The AI reviews its own generated draft. If the content is flagged as potentially harmful or if the AI outputs the special code NO_REPLY, the draft is discarded and nothing is posted.
This runs before all gates. If a page has sent 1,000 replies in the current calendar day, the bot immediately stops and sends you an alert email. This protects against Facebook velocity bans and runaway API costs from viral posts.
10. The Leads Vault
The Leads Vault is an automatic lead preservation system for businesses that use the Operating Schedule feature.
How It Works
- A comment arrives while your schedule is closed (e.g., 11pm on a Saturday)
- Instead of ignoring it, the system saves it as a
vault_capturedlog entry with all metadata - The Recovery Worker runs every 20 minutes 24/7
- When the schedule opens (e.g., Monday 9am), the worker finds all vaulted entries
- It resubmits each entry through the full AI pipeline, which generates and posts a reply
- The original vault entry is deleted to prevent duplicates
12. Delays & Timing
| Timing Parameter | Value | Purpose |
|---|---|---|
| Reply Typing Delay | 15β60 seconds (random) | Mimics a human typing a response β avoids bot detection |
| Deduplication Window | 60 minutes | Won't reply to the same user twice within this window (per post) |
| Media Scheduler Run | Every 5 minutes | Checks for scheduled posts that are due to be published |
| Recovery Worker Run | Every 20 minutes | Processes vaulted leads + replays emergency buffer events |
| Bot Skip Rate | 20% of replies | Random skip to appear more natural |
| Emergency Buffer Replay | 50 events/run | Rate-limits recovery to prevent thundering herd issues |
| Vault Replay per Run | 20 events/run | Prevents overload when schedule reopens after a long holiday |
13. Analytics Guide
Access via: Dashboard β any page card β π Stats
KPI Cards (Top Row)
| Metric | What It Measures |
|---|---|
| Total Audience | Total Facebook followers on the connected page (fetched live from Graph API) |
| Active Conversations | Unique users who engaged during the selected period, with % growth vs previous period |
| Open Rate | Percentage of Messenger messages that were read (from read receipt events) |
| Click-Through Rate (CTR) | Percentage of interactions that included a link click or postback button press |
Charts
- Engagement Timeline: Daily interaction counts. Drag to zoom. Use the 24H/7D/30D/90D/All buttons to change the window.
- Peak Activity Hours: Bar chart of UTC hours when your audience is most active. Use this to set optimal operating hours.
- Top Engaged Users: Bar chart of your most active commenters/messengers.
- Most Active Conversations: Table of posts that generated the most AI replies, with direct Facebook links.
Optimization Insight
If SocialConductor detects that your page would benefit from a plan upgrade based on activity patterns, a π Optimization Insight banner appears with a specific recommendation.
14. Reading the Comment Logs
Access via: Dashboard β any page card β π Logs
The Conversation View
Each log entry is displayed as a chat bubble pair:
- Grey bubble (left): The user's original comment or message
- Blue bubble (right): The AI's reply. If empty, the AI was blocked by a gate or was in simulation mode.
Log Types Explained
| Log Type | Meaning |
|---|---|
comment | A public comment on a post that received an AI reply |
message | A Messenger DM that received an AI reply |
simulation | AI generated a draft reply but it was NOT posted (Simulation Mode was on) |
vault_captured | Comment received outside operating hours β saved for later processing |
message_read | A user read a Messenger message the AI sent (from Facebook read receipts) |
postback | A user tapped a quick reply button on your Page |
Searching & Filtering
- Use the search bar to find logs by user name, message text, or AI reply text
- Use time filters (24H / 7D / 30D) to narrow the view
- Use per-page dropdown (20/50/100) to see more records at once
- Use Export CSV to download all log data for CRM import or offline analysis
15. Alerts & Notifications
Configure alerts in βοΈ Profile β Alert Triggers. Alerts are sent to your registered email address.
| Alert | When Triggered |
|---|---|
| Usage Warning (90%) | When a page has used 90% of its daily reply limit |
| Circuit Breaker Hit | When a page reaches the 1,000 daily hard cap β CRITICAL |
| Billing Alert | Upcoming plan expiry or payment issues |
| Login Alert | A new device or browser logged into your account |
| Database Alert | System automatically emails support if the DB goes offline (for SocialConductor operations team) |
Email frequency can be set to: Immediate, Daily Digest, Weekly Summary, or Disabled.
16. Instagram Features
SocialConductor.AI supports both Facebook and Instagram through the same platform. Instagram is connected via your Facebook Business account or directly as an Instagram Business/Creator account.
Connecting Instagram
On the login page, use Login with Facebook if your Instagram Business account is linked to a Facebook Page (most common), or Continue with Instagram Only for standalone Instagram Business/Creator accounts. After connecting, you'll see your IG account listed under each Facebook Page it's linked to on the Dashboard.
Instagram Comment Replies
When someone comments on your Instagram posts, the AI generates and posts a reply β exactly like Facebook comments. Log entries show a πΈ Instagram badge so you can distinguish them from Facebook activity at a glance.
Instagram DMs
Instagram Direct Messages are handled automatically when DMs is toggled ON in βοΈ Edit AI. The AI reads the incoming DM, generates a contextual reply, and sends it back via the official Messenger API. Requires instagram_manage_messages permission.
Editing Instagram Replies
Instagram does not allow editing comments via API. When you click βοΈ Edit on an Instagram log entry, SocialConductor deletes the original reply and posts a new one with your edited text. The log entry is updated with the new comment ID automatically.
Platform Filter in Logs
The Logs page has a tab bar at the top: π All, π΅ Facebook, and πΈ Instagram. Click any tab to see only that platform's activity. The filter persists across time frame changes.
Instagram Analytics
When Instagram is linked, the Analytics page shows a dedicated Instagram Insights card with: follower count, total posts, 28-day reach, impressions, profile views, follower delta, and a recent media grid. The AI Insight Report also incorporates your Instagram data alongside Facebook metrics for cross-platform recommendations. Requires instagram_manage_insights Advanced Access.
instagram_basic β comment reading and reply postinginstagram_manage_messages β DM reading and sending (Advanced Access)instagram_manage_insights β follower metrics, reach, impressions (Advanced Access)
17. IG Following & Personal List
You may not want the AI to automatically reply to accounts you personally follow on Instagram, or specific Facebook commenters you've marked as personal contacts. The Personal List and IG Following Sync give you granular control.
How It Works
When someone on the Personal List or IG Following list comments, the AI still generates a reply β but holds it as a draft instead of posting. You'll see it in the Logs with a πΈ IG Following β DRAFT HELD or π Personal β DRAFT HELD badge, plus a "AI would have replied: β¦" preview. You can post the draft with one click or write your own reply.
IG Following Auto-Sync
Meta does not expose the following list for Business/Creator accounts via the Graph API. Instead, you import it manually from Instagram's data export β a one-time process you can repeat whenever your following list changes.
How to Import Your Following List
- Open Instagram β tap the β° menu (top right) β Settings and activity
- Search "down" in the settings search bar
- Tap Download your information β this opens Meta Accounts Center
- Tap Create export
- Select your Instagram account β under Connections, select Following
- Set the format to JSON β submit the request
- Wait for the email from Instagram (usually a few minutes to hours)
- Download and extract the ZIP β find following.json inside the
connections/followers_and_following/folder - Go to Moderation Panel β πΈ Instagram Following β expand β¬οΈ Import from Instagram Data Export β upload the file
Per-Account Toggle
In the Moderation Panel, each person on the Personal List or IG Following list has a toggle switch:
- β Hold (default) β AI generates a draft but holds it for your review
- π€ Auto β AI replies normally, just like any other commenter
Adding to Personal List Manually
From the Logs page, click the π Personal button on any log entry to add that commenter to your personal list. Facebook users can only be added manually (Facebook's API does not provide a friends/following list for Pages).
18. Moderation Panel
Accessible from the sidebar or via the Logs page, the Moderation Panel gives you full control over who the AI responds to.
Sections
| Section | What it controls |
|---|---|
| π« Blocked Users | AI ignores all comments/DMs from these users silently |
| πΈ Instagram Following | Accounts auto-synced from your IG; AI holds drafts by default, toggleable per account |
| π Personal List β Manual | Accounts you've manually added; same draft-hold behaviour, same toggle |
| ποΈ Hidden Users | Comments from these users are processed normally but hidden from the Logs view |
Search
Use the search bar at the top of the Moderation Panel to filter any list by username. The search applies to all sections simultaneously.
Pagination
Each section shows 20 entries per page. For large IG Following lists, use the page number controls at the bottom of each section to navigate.
CSV Exports
Three export buttons at the top right download each list as a CSV file:
- β¬οΈ Blocked CSV β username, reason, blocked date
- β¬οΈ IG Following CSV β username, bot reply status, date added
- β¬οΈ Personal CSV β username, bot reply status, date added
The Logs page also has an β¬οΈ Export CSV button in the timeframe bar that downloads your last 5,000 interactions including all message content, timestamps, and reply types.
19. Security Architecture
All Facebook and Instagram access tokens are encrypted in the database using Fernet symmetric encryption (AES-128-CBC). The encryption key is stored as an environment variable and never in source code. Tokens are decrypted only at the moment of an API call and never logged.
User-generated content (comments, DMs) is always passed as user content β never concatenated into the trusted system instruction. A security guardrail is appended to every AI prompt preventing it from disclosing system configuration, tokens, or user data even if instructed to by a crafted comment. Viral few-shot examples are screened for injection phrases before storage.
Every incoming Facebook webhook is verified using a secret-key HMAC signature. Any event that fails this check is rejected with HTTP 403.
All form submissions and API calls use unique per-session CSRF tokens combined with referrer validation. This prevents cross-site request forgery attacks on critical actions.
The webhook endpoint is rate-limited to 100 requests per 60 seconds per IP. All API command endpoints (including OpenClaw) are rate-limited per user/key. Brute-force protection includes delays on invalid coupon attempts.
All database queries use parameterized queries via psycopg2. No raw string interpolation is used for SQL. All user inputs are sanitized and length-limited before storage.
20. Billing & PayPal Integration
How Payments Work
- Select one or more pages using checkboxes on the Dashboard
- A yellow billing bar appears β choose your plan (Basic/Enhanced/Enterprise) and billing type (30 Days or Recurring)
- The total is calculated server-side (not modifiable by the client)
- Click the PayPal button and complete payment in the PayPal pop-up
- On success, the selected pages are instantly upgraded in the database
- A subscription expiry date is set 30 days from payment
Automatic Downgrade
When you log in to the dashboard, the system checks all your pages for expired subscriptions. Any page where subscription_end has passed is automatically downgraded to the Free plan. You will see a notification in the dashboard.
Coupon Codes
Promo codes can be redeemed in the "Redeem Coupon" bar on the Dashboard. Each code adds a fixed number of bonus credits to a selected page. Bonus credits are used as an overdraft once the daily plan limit is reached. Each coupon is single-use.
21. Troubleshooting
β The AI isn't replying to comments
1. Comment Reply toggle β Is it ON in βοΈ Edit AI?
2. Simulation Mode β Is it OFF? If ON, replies go to Logs only.
3. EULA β Have you accepted the Terms of Service? Check Profile page.
4. Operating Schedule β Is it enabled but the current time is outside your set hours?
5. Gate 2 β Was the comment under 4 words? ("Cool!" won't get a reply)
6. Gate 1 β Did you comment yourself with an admin account? (Self-reply protection)
7. Daily Limit β Has the page hit its daily reply limit? Check Dashboard stats.
8. Trial Status β Is your trial expired (Day 14+)? Upgrade or check the banner.
β "Post Now" button shows an error on the Logs page
β Logs page shows no activity
2. Try the time filter "All" to see historical data.
3. If you recently reconnected your Facebook account, log out and back in β your access token may have been refreshed and the webhook needs re-registration.
4. Check that your Facebook Page is subscribed to the webhook (done automatically on login, but can be re-triggered by reconnecting).
β Analytics charts show no data
β Image editor is slow to load or shows a blank canvas
β Facebook OAuth shows "This app is in development mode"
β PayPal payment succeeded but plan was not upgraded
Contact us at [email protected]. Include your Page ID, a description of the issue, and screenshots if available. Typical response time: 24β48 hours (MonβFri).
11. Social Listening
Social Listening is the AI's ability to understand the context of a conversation β not just the individual comment.
What the AI Reads Before Replying
How It Affects Replies
The AI is instructed to: