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 6-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 |
📷 Shooting on a real camera? You can upload straight from a Canon, Nikon, or Sony body (including RAW) over a private SFTP connection — see Section 26 — Camera Direct Upload.
9. Safety Gate Pipeline
Every incoming comment or message passes through a sequential gate pipeline before the AI is allowed to respond. Gates run in a fixed order; the first one that fails ends processing for that event. Most blocks are logged to your Comment Logs with a reason badge (so you can see exactly why something was skipped), and a few sensitive categories are routed to human review instead of being auto-answered. This is what keeps your account safe, your costs predictable, and your replies appropriate.
The gates evolved well beyond the original six. Numbering uses decimals (0.1, 0.3, 2.5…) because new gates were inserted between existing ones over time — the numbers reflect order in the pipeline, not importance.
Stage 0 — Identity, spam & idempotency
Drops events where the commenter is your own Page/admin account, preventing infinite reply loops.
When Vacation/Away Mode is on, events are silently dropped — or, if you chose "draft silently," queued as drafts for later review instead of being posted.
Checks the commenter against your block list (dropped, logged) and your personal list (handled per your personal-list rules rather than the normal AI flow).
Always on. Blocks three patterns: velocity (too many comments from one user in 10 minutes), duplicate (the same text repeated), and template fishing (many commenters posting an identical copy-paste template to farm replies). Each is logged with its own reason.
Auto-blocks comments matching known scam/phishing signatures (fake giveaways, crypto, impersonation links).
Ensures a given comment/DM is only processed once, even if Facebook delivers the webhook multiple times or two Gunicorn workers pick it up simultaneously. Critical for preventing duplicate replies.
If you've reserved a specific post or video for manual replies only, the AI stays out of its comments.
If you've already replied to a thread by hand, the AI backs off so it never talks over you.
Stage 1 — Conversation awareness
Scans recent activity (about the last hour) for this user on this page. If we replied recently, we skip — unless the user is replying to us, in which case we allow a natural back-and-forth.
Caps how many times the AI will go back and forth in a single thread (see Section 19) so conversations don't spiral.
Stage 2 — Content & intent screening
Skips ultra-low-effort comments ("Cool!", "😍") and attachment-only comments with no text — they don't warrant a business reply and would waste credits. Genuine leads are exempt.
If a commenter is clearly talking to another tagged person rather than to your page, the AI stays out of the conversation.
Detects comments attacking the page/creator directly (insults, "you're a bot," etc.). Never auto-replied — routed to human review so you decide how to respond.
Flags legal threats, copyright/DMCA claims, "I reported you," and breaking-incident language. Routed to human review — the AI must never improvise on legal or liability matters.
Catches bereavement, serious illness, disability, minors disclosing their age, and mental-health crisis language. Routed to human review so a person handles anything sensitive with care.
When a commenter challenges a fact, date, number, or asks for a source, the reply is routed to human review rather than letting the AI guess.
Stage 3 — Human emulation, schedule & limits
Randomly skips a share of eligible comments so your page never replies to literally everything like an obvious bot.
Enforces your Operating Schedule in your configured timezone. Outside active hours, high-intent comments are still captured to the Leads Vault (Section 10) even though no reply is sent.
Adds a randomized human-like delay (roughly 30–120s) before posting, so replies don't land instantly. Social context is re-read after the delay so the AI sees the freshest state of the thread.
Verifies the page still has daily reply credits and monthly token budget before any AI call. Protects against velocity bans and runaway API costs.
Stage 4 — Output safety
The AI reviews its own draft. If it emits the sentinel NO_REPLY or the draft fails the content check, nothing is posted. Drafts that hit a watch phrase are held (🔔) for your approval with Send / Edit buttons and an email alert, instead of auto-posting.
A page-level hard cap runs ahead of the pipeline. Once a page hits its daily reply ceiling, the bot stops and emails you — a last line of defense against velocity bans and viral-post cost spikes.
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. Conversation Depth Limits
By default the AI replies once per thread (depth = 1). This prevents runaway back-and-forth conversations that consume your daily reply budget and can feel spammy. You can increase the limit per platform in ⚙️ AI Settings → 🔁 Conversation Depth Limits.
How it works
| Platform | Setting | How depth is counted |
|---|---|---|
| 📘 Facebook Comments | fb_comment_depth | Bot replies on the same post thread |
| 💬 Facebook Messenger | fb_dm_depth | Bot replies to this user on this thread |
| 📸 IG Comments | ig_comment_depth | Bot replies to this comment/media thread |
| 📩 IG DMs | ig_dm_depth | Bot replies to this sender today (resets daily) |
In the Logs
When depth is hit, the entry shows a red 🔁 Gate 1.5 — Depth Limit or 🔁 Gate 5.5 — Depth Limit badge with an explanation: how many times the bot replied, what the max is, when the last reply was sent, and a link to the setting to adjust it.
Each reply counts against your plan
Every reply at any depth level runs through check_usage() and counts toward your daily plan limit. Reducing depth to 1 directly reduces plan consumption and Gemini API costs.
20. Lead Funnel
The Lead Funnel converts first-time DM senders into buyers using a ManyChat-style automated sequence — without requiring any third-party tools.
Setting it up
Go to ⚙️ AI Settings → 🎯 Lead Funnel. Enable it for Facebook, Instagram, or both. Then configure:
| Field | Purpose |
|---|---|
| Welcome Message | Sent on first DM. Should greet them warmly and ask which topic they want to learn about. End with a question to prompt them to tap a button. |
| Topic 1–3 Button Labels | Short labels (max 20 chars) shown as quick-reply buttons. E.g. "Train Photography" |
| Topic 1–3 Reel Links | Instagram/Facebook reel URL sent when they tap that topic button |
| Topic 1–3 DM Messages | Sent before the reel link — 2–3 sentences of genuine value about that topic |
| CTA After Reel | One sentence appended after every reel link (e.g. "Let me know what you think!") |
AI Generation
Click ✨ Generate with AI to have Gemini write all fields automatically. You can seed it from:
- None — enter your niche and topic hints manually
- 🅰️ Prompt A — uses your existing AI persona as the voice reference
- 🅱️ Prompt B — uses your B variant if configured
Always review and edit the generated content before saving — the AI gives you a strong starting point that you personalise.
Funnel Contacts
Every person who enters the funnel is tracked in the Funnel Contacts table (expandable at the bottom of the Lead Funnel settings). Columns show their PSID (anonymised), platform, current stage (welcomed → topic_sent → in_automation), which topic they chose, and last activity time.
21. Block & Hide — Platform-Level Actions
The Block and Hide buttons in the Logs page now make real Facebook Graph API calls in addition to updating your local database.
Block User
Clicking 🚫 Block User on a log entry does two things simultaneously:
- Adds the user to your
blocked_userstable — the AI ignores all future comments and DMs from them (Gate 0.1) - Calls
POST /{page-id}/blockedwith their PSID — bans them from your Facebook Page at the platform level, so they can no longer comment publicly
pages_manage_engagement permission. If the API call fails, the local block still applies and a specific flash message explains the issue.Hide Comment
Clicking 👁️ Hide Posts does two things:
- Adds the user to
hidden_users— their entries are filtered from your Logs view - Calls
POST /{comment-id}withis_hidden: true— hides that specific comment from your Page's public view. The commenter can still see it (Facebook's standard hide behaviour) but no one else can.
22. Bell Notifications
The 🔔 bell icon in the top-right topbar appears on every page and shows system alerts relevant to your account.
Alert types
| Alert | Trigger | Resets |
|---|---|---|
| 🛠️ Maintenance | A system message inserted by SocialConductor admins | When the message is removed |
| ⚠️ Near Limit | A page reaches 90% of its daily reply plan | Next day (key includes date) |
| 🚨 At Limit | A page hits 100% of its daily reply plan — AI stops replying | Next day |
Dismissing alerts
Click the ✕ button on any alert to dismiss it. Dismissed alerts are stored per-user in the alert_dismissals table. Usage alerts reappear the next day automatically since their key includes today's date. Maintenance alerts stay dismissed until a new message is posted.
How it renders
Alerts are rendered server-side inline in the page (no JavaScript fetch required) so there is no "Loading..." flicker and no dependency on a separate API call succeeding. The bell badge count reflects the number of active, non-dismissed alerts.
23. 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.
24. 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.
25. 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
Email [email protected] or call 571-758-2754. Include your Page ID, a description of the issue, and screenshots if available. Typical response time: 24–48 hours (Mon–Fri).
26. Camera Direct Upload (SFTP)
Camera Direct Upload lets you push photos straight from a camera body into your Media library over a private, encrypted SFTP connection. Modern Canon, Nikon, and Sony cameras can FTP images as you shoot — this feature gives each account its own isolated SFTP login, auto-develops the images (including RAW), and drops them into an approval queue. It was built for event, airshow, and trackside photographers who want shots online minutes after pressing the shutter.
How it works
- Provision a session. In the Camera panel, name your shoot and click Provision. You receive a dedicated SFTP host, port, username, and password. The password is shown once — store it in your camera's FTP settings right away.
- Configure your camera. Enter the host/port/username/password in your camera's FTP/SFTP transfer settings. Passwords are alphanumeric-only for compatibility with camera virtual keyboards (Canon 1DX/R-series reject special characters).
- Shoot. As images transfer, the server picks them up automatically, develops RAW files, applies adaptive enhancement, and stores the result.
- Review & approve. Uploaded shots land in the Ingest queue. Approve the keepers (they move into your Media library and become postable like any other image) or reject the rest.
Image processing
Every upload is processed entirely in memory and stored exactly like a web upload, so it works with scheduling, captions, and posting with no extra steps. When AI editing is enabled, the pipeline applies (in order): RAW development, gentle denoise, shadow lift, auto-levels, and capped sharpness/saturation/contrast, then resizes to 4096px on the long edge and saves at high-quality JPEG. With AI editing off, RAW files are still developed but otherwise left untouched.
| Supported | Formats |
|---|---|
| JPEG | .jpg / .jpeg |
| Canon RAW | .cr3 / .cr2 / .crw |
| Nikon RAW | .nef / .nrw |
| Sony RAW | .arw / .srf |
| Adobe DNG | .dng |
Security & isolation
- Each account gets its own chroot-jailed SFTP user — you can only ever see your own upload directory.
- SFTP passwords are stored encrypted at rest and can be rotated at any time from the Camera panel (rotating also re-creates the login if it was lost during a server rebuild).
- Every state change (provision, rotate, file received, ingest, approve, reject) is written to an audit event log.
- Upload paths are validated to block path-traversal attempts before any file is processed.
27. OpenClaw & Claude Code
OpenClaw is the integration layer that lets you control your SocialConductor bot from outside the web dashboard — from a chat app, the Claude Code / OpenClaw skill, or the SocialConductor iPhone app. It exposes a secure, token-authenticated API so you can check status, read logs, manage leads, post and regenerate replies, edit prompts, and pull analytics without opening a browser.
Linking your account
- Request a one-time link from your chat app or the mobile app. This generates a short-lived link token.
- Open the link (
/openclaw/link). It validates the token and runs the normal Facebook OAuth handoff, tying your OpenClaw access to your real page. - Once linked, an API key (Bearer token) is issued. All subsequent commands authenticate with that token — there's no password to share.
Link tokens expire quickly by design. If a link says it's expired, just request a fresh one.
The Magic Prompt
Rather than writing a system prompt by hand, the Magic Prompt generator reads your real Facebook Page profile (bio, about, description, categories) through the Graph API and drafts a tailored prompt for you. You can nudge it with optional voice, audience, and avoid hints. The page profile is cached for 7 days to keep it fast. This is the same engine behind the web "auto-generate prompt" button — see Section 4.
What you can do over OpenClaw
- Monitor: live status, page list, comment logs, drafts, leads, blocked users, viral vault, security audits.
- Act: post a manual reply, regenerate an AI reply, approve drafts in bulk, hold/release replies, block/unblock users, toggle vacation mode.
- Configure: read and update your system prompt, advanced settings, and live settings.
- Analyze: standard and enhanced analytics, A/B stats, sentiment trends, commenter profiles, top videos, and AI insights.
- Teach: feed examples back to the AI to shape its voice over time.
- Reviews: read, draft, generate, and post Business Review replies.
Security model
- OpenClaw endpoints use Bearer-token auth and are rate-limited per key (for example, Magic Prompt generation is capped per page per day).
- The token is scoped to your linked page(s) only — strict tenant isolation applies exactly as it does on the web.
- OpenClaw routes are exempt from browser CSRF (they carry no cookie) because the Bearer token itself is the credential; they are never reachable with a stale session cookie.
28. iPhone App
The SocialConductor iPhone app puts your comment automation in your pocket. It's available on the App Store and connects to the same backend as the web dashboard, so anything you do in the app is instantly reflected on the web and vice-versa.
Signing in
The app uses the same OpenClaw link + Facebook OAuth handoff described in Section 27. After you authorize, the app stores a Bearer token securely in the iOS Keychain — never in plaintext — and uses it to reuse the same secure API the web dashboard uses behind the scenes.
What's in the app today
- Unified chat view across platforms with date separators and per-platform tabs.
- Status & control: pause/resume replies, hold drafts, toggle vacation mode.
- Comment logs with the comment's context and vibe, and one-tap AI-reply regeneration in the reply editor.
- Leads & moderation: review captured leads, block/unblock users, post manual replies.
- Magic Prompt generation for fast onboarding.
Platform coverage & roadmap
Facebook & Instagram are wired up first. TikTok and YouTube control from the app, full analytics views (learning analytics, top videos), per-platform settings screens, and push notifications for new replies across all platforms are on the near-term roadmap. Until push lands, use the in-app refresh and the email alerts described in Section 15 to stay on top of activity.
29. Contact & Support
Reach the SocialConductor.AI team directly. Typical response time is 24–48 hours, Monday–Friday.
| Sales | [email protected] Plans, agency/multi-account setups, and upgrades. |
| Support | [email protected] Technical issues, billing questions, and account help. Include your Page ID and screenshots. |
| Phone | 571-758-2754 Mon–Fri. Email is fastest for issues that need logs or screenshots. |
For account-specific requests, email from the address on your account and include your Page ID so we can verify and resolve faster.
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: