Documentation
SocialConductor Studio — Complete configuration & feature reference
🚀 Getting Started
- Connect Your Channel — Click Sign In with Google on the home page and authorise the required permissions.
- Complete the Setup Wizard — New accounts are guided through EULA acceptance, prompt configuration, and core settings automatically. New
- Start in Simulation Mode — Keep Simulation Mode ON while you review AI replies in the Logs tab. No comments will be posted.
- Go Live — When you're satisfied with reply quality, disable Simulation Mode and enable Auto-Reply to start posting.
- Monitor & Tune — Use the Analytics panel and AI Insight card on the Dashboard to optimise over time.
📋 Onboarding Wizard New — April 2025
First-time users are automatically redirected to a 3-step setup wizard after connecting their Google account.
New Account Flow
- Step 1 — Terms of Service: Read and accept the EULA. Your acceptance is recorded with IP address, user-agent, and timestamp for compliance.
- Step 2 — System Prompt: Write your own prompt or use Magic Generate to have Gemini analyse your channel and create a tailored persona automatically.
- Step 3 — AI Settings: Configure Auto-Reply, Simulation Mode, Top Commenter Engagement, and Video Recommendations in one place.
Existing Account Flow
Accounts that existed before the wizard was deployed see a Verify Your Setup variant — the EULA step is skipped (your prior acceptance is shown), and Steps 2 & 3 let you validate and update your current settings before marking the wizard complete.
🛡 Safety Gates
Comments pass through a layered gate pipeline before any AI reply is generated or posted. Gates run in order; the first gate to trip ends processing for that comment.
comments.list call for deeper threads.NO_REPLY are suppressed.⚡ Core Switches
🤖 Enable Auto-Reply
The master power switch. When OFF, the polling loop skips this channel entirely — no comments are read, no replies generated. When ON, the channel participates in every polling cycle (every 5 minutes).
🧪 Simulation Mode
When ON, the AI generates replies and saves them to Logs with status simulated, but never posts to YouTube. Use this to preview reply quality before going live. You can manually approve and post individual replies from the Logs page.
🏖 Hold / Away Mode
Temporarily pauses all AI replies without disabling the bot. Ideal when you're travelling or unavailable. The timestamp when Hold was activated is displayed in the toggle. All incoming comments queue silently and will be processed when Hold Mode is turned off.
✍ System Prompt
Defines your AI's personality, tone, and rules. Injected into every reply generation call alongside three live context variables:
{context_str}— the video title and description (tells the AI what the video is about){others_saying_str}— a sample of recent comments on this video (sets the room vibe){comment}— the specific comment being replied to
“You are a knowledgeable tech reviewer for {context_str}. The community is saying: {others_saying_str}. Reply to: {comment}. Be helpful, enthusiastic, and mention specs when relevant. Under 35 words.”
✨ Magic Generate
Calls Gemini to analyse your channel title, description, and 5 most recent video titles, then writes a tailored system prompt with all three required variables pre-populated. Available in both the Wizard and the Settings page.
🧪 A/B Prompt Testing
When enabled, each incoming comment randomly uses Prompt A (your main prompt) or Prompt B (a second variant). The prompt_variant column in Logs shows which was used, letting you compare engagement and quality between the two.
✨ AI Features
⭐ Top Commenter Engagement New — April 2025
When enabled, SocialConductor identifies your most active community members (top 25 commenters by AI-replied comment count over the past 30 days) and injects an EXTRA INSTRUCTION block into the prompt for those users. The AI is instructed to:
- Use the commenter's @username in the reply
- Acknowledge their loyalty or continued engagement
- Ask a genuine follow-up question to deepen the conversation
The commenter ranking table is visible in Settings (expand View top commenters) and refreshes in real time. Recognised commenters are logged with a ⭐ prefix in the console.
🎬 Video Recommendations New — April 2025
When enabled, the AI appends a natural recommendation for one of your other top-performing videos at the end of its reply. The recommended video is selected by finding the most-commented active video in your channel that is not the video being commented on.
First Comment Only (sub-option)
When enabled (default), the recommendation is only added the very first time the AI replies to a given commenter. Returning commenters who have already received a recommendation will not see it again — preventing the suggestion from feeling repetitive.
The recommendation is formatted as a casual inline suggestion (e.g. “You might also enjoy my video on [title]: youtube.com/watch?v=...”) and is logged at the console with a 🎬 prefix.
🧹 Bot-Tell Scrubbing & Reply Naturalness New — April 2025
A two-layer defense against AI replies that publicly signal the account is run by a bot.
Layer 1 — Prompt Hardening
A _ANTI_BOT_PROMPT_INJECTION block is prepended to every Gemini prompt before any other instructions. It explicitly forbids the model from using sycophantic openers (Absolutely!, Great question!, Certainly!), helper-bot phrases (I'd be happy to, Feel free to, Don't hesitate), and self-identifying language (As an AI). The model sees this as a hard constraint, not a suggestion.
Layer 2 — Post-Generation Regex Scrubber
Even if the model slips through (rare but possible), scrub_bot_tells() runs a regex pass on every generated reply before it is stored or posted. Matched phrases are either removed or replaced with natural equivalents. Scrubbed replies are tracked with bot_tell_scrubbed=1 in history and counted in the Analytics Reply Naturalness card.
Reply Naturalness Analytics Card
The Analytics page shows a Reply Naturalness & Edit Rate card that tracks:
- Edit Rate — % of AI-posted replies that the tenant manually changed before posting. Computed by comparing the posted text against the original AI draft.
- Tiers — <15% (Great), 15–30% (Review Recommended), >30% (Action Required) with inline recommendations for each tier.
- Bot-Tells Scrubbed — total count of phrases automatically cleaned before posting.
⏱ Response Speed Override
By default the bot waits a random 30–60 seconds before posting (Gate 3.2 human emulation). The Speed Override replaces this with a named profile:
When the override is disabled, the default 30–60 second randomised delay applies.
📅 Scheduling
Restrict bot activity to specific hours and days. When a comment arrives outside the active window it is not processed — it will be picked up in the next polling cycle that falls within the window.
- Fixed — replies only between the exact start and end times you specify
- Randomised (넰30 min) — shifts your start and end times by a random offset each day to avoid detectable patterns
- Active Days — restrict to specific days of the week (Mon–Sun)
- Timezone — all times are interpreted in your chosen timezone
👥 Friends List & Subscriptions
Manage how the AI handles comments from specific users. Each entry has an Action:
friend_reserved.Subscription Sync
Click Sync Subscriptions to import all channels you subscribe to on YouTube. They are added with simulate_only action and source=subscription. Re-syncing updates existing subscription rows without touching manually-added friends.
🔧 Advanced Settings
🔒 Reserved Videos (Video Blacklist)
Enter YouTube video IDs (one per line or comma-separated) to exclude from AI automation. The AI will skip all comments on these videos — they appear in Logs as video_reserved for your manual reply. Useful for sensitive uploads, sponsor videos, or pinned announcements.
🎯 Lead Trigger Words
Comma-separated keywords. When a comment contains any of these words, the AI still replies normally, but the comment is flagged as a 🎯 Lead in Logs so you can follow up personally. Useful for purchase intent signals like price, buy, how much, link, order.
💬 Conversation Depth Limit
Sets how many AI replies are allowed per user per video before Gate 1.6 kicks in. Default is 3. Range: 1–10. Lower values conserve daily credits; higher values support deeper community conversations.
🐟 Spam & Phishing Detection
Gate 0.7 scans each comment for known spam signals: giveaway scams, prize claim language, suspicious shortened URLs, and contact harvesting patterns. When triggered:
- The comment is silently skipped (no pending history row created)
- If Auto-block offenders is enabled, the user is added to
spam_moderationand all future comments from them are ignored
💬 Cross-Talk Gate (Gate 2.1)
Skips comments that open with an @mention directed at another commenter. Prevents the AI from interjecting into side conversations between your viewers.
💳 Billing & Plans
| Plan | Daily Replies | Price |
|---|---|---|
| Free / Trial | 30 | Free (14-day trial) |
| Basic | 30 | $99 / mo |
| Enhanced | 50 | $199 / mo |
| Enterprise | 80 | $299 / mo |
Bonus Credits
One-time credit packs add to your daily limit for that day. Credits burn before your plan limit. Available in 10, 20, and 30 reply increments from the Dashboard.
Coupons
Redeem coupon codes from the Dashboard. Each code grants bonus reply credits and is single-use.
🔧 Troubleshooting
FOR UPDATE NOWAIT lock releases during mid-loop commits and has been resolved. The current system uses an atomic INSERT ... ON CONFLICT DO NOTHING claim pattern ensuring only one worker across all servers can process a given comment ID.
{context_str}, {others_saying_str}, {comment}) must all be present for full context injection.
📋 Changelog
edited_by_tenant, original_ai_reply) added to history./api/top_commenters endpoint.simulate_only action.