Social Listener

Complete guide to your Social Media Listening Tool

Part of Wosuol System · Version 3.0 · AI Powered by Google Gemini

1. System Overview 2. How It Works (Architecture) 3. Dashboard Guide 4. Managing Targets 5. AI Reply Suggestions

6. Sentiment Analysis (Gemini) 7. n8n Workflow 8. API Reference 9. Troubleshooting

1. System Overview

Social Listener monitors your brand, name, or product across social media platforms. It automatically:

Scrapes mentions from Facebook, Instagram, Twitter/X, TikTok, LinkedIn, and the web
Analyzes each mention using Google Gemini AI to classify sentiment (Positive / Negative / Neutral / Offensive)
Generates AI replies for every mention - professional, tone-matched, and in the same language as the original post
Alerts you to negative or offensive mentions that need attention
Tracks trends over time so you can see if your reputation is improving or declining

Key Components

Dashboard (index.php)	Visual interface to see all mentions, charts, stats, and AI replies
API (api.php)	Backend that handles data processing, AI sentiment analysis, and reply generation
Database (MySQL)	Stores all mentions, replies, and monitoring targets
n8n Workflow	Automation that scrapes social media every 30 minutes
Apify	Cloud scraping service that collects data from Facebook, Instagram, Google, etc.
Google Gemini AI	AI that classifies sentiment and generates professional reply suggestions (FREE)

2. How It Works

Every 30 minutes, this happens automatically:

n8n triggers → Reads your targets → Apify scrapes social media → Gemini AI analyzes sentiment → Gemini generates reply → Saved to database → Appears on dashboard

Data Flow

n8n Schedule Trigger fires every 30 minutes

n8n reads targets from your API: GET api.php?action=get_targets

For each target, n8n calls the appropriate Apify scraper (Google Search for keywords, Facebook scraper for pages, Instagram scraper for accounts)

Scraped results are normalized into a unified format (platform, author, content, URL)

Each mention is sent to your API: POST api.php?action=process_mention

Your API calls Gemini AI to classify sentiment + generate a reply suggestion, then saves everything to MySQL

Dashboard displays everything with real-time charts, color-coded alerts, and AI reply buttons

3. Dashboard Guide

Stat Cards (Top Row)

Total Mentions	Total number of social media mentions collected. Shows today's count below.
Risk Alerts	Count of Negative + Offensive mentions. Red border and pulse animation when active. These need your attention first.
Pending Review	Mentions you haven't marked as "handled" yet. Your to-do list.
Handled	Mentions you've reviewed and marked as done.

Charts

Mentions Timeline - Shows activity over the last 14 days. Blue line = all mentions, red dashed = risk mentions. Spikes indicate viral events or coordinated attacks.
Sentiment Analysis - Doughnut chart showing the percentage breakdown of Positive / Negative / Neutral / Offensive mentions.
Platform Distribution - Horizontal bar chart showing which platforms generate the most mentions.

Live Feed Table

Red rows = Negative sentiment
Orange rows = Offensive sentiment
Faded rows = Already handled
Click post content to expand and read the full text

Action Buttons (per row)

View	Opens the original post on social media in a new tab
Handle	Marks the mention as reviewed/handled (updates instantly)
Reply	Opens the AI Reply modal with a generated professional reply you can copy
Delete	Permanently deletes this mention from the database

Toolbar Buttons

Refresh	Manually refresh stats (also auto-refreshes every 60 seconds)
Export	Downloads all visible mentions as a CSV file
Config	Open the monitoring target configuration
Guide	Opens this user guide
Theme	Toggle dark/light mode (saved in your browser)

Filters

Use the filter dropdowns above the feed table to narrow down results:

Platform - Show only Facebook, Instagram, Twitter, etc.
Sentiment - Show only Positive, Negative, Neutral, or Offensive
Status - Show only Pending or Handled
Search - Free text search across all visible content

Clear All

The Clear All button (red, next to "Live Feed") deletes ALL mentions from the database. It requires double confirmation. Use this to reset your data and start fresh.

4. Managing Monitoring Targets

Targets tell the system what to search for. Click "Config" in the navbar to manage them.

Target Types

Type	What to Enter	What It Does
keyword	Any text: brand name, person name, product	Searches Google for mentions on Facebook, Instagram, X, TikTok, and LinkedIn
facebook_page	Full URL: `https://facebook.com/pagename`	Scrapes up to 50 recent posts and 100 comments from that page
instagram_account	Handle: `@username`	Scrapes up to 50 recent posts from that account
twitter_handle	Handle: `@username`	Future: will search Twitter/X mentions directly
url	Any website URL	Future: will monitor that URL for changes

Best Practices

Add your brand name in both English and Arabic as separate keyword targets
Add your competitors' names as keywords to compare sentiment
Add your own Facebook page URL to monitor comments on your posts
Use the toggle switch to temporarily disable a target without deleting it
Start with 3-5 targets. Each target uses Apify credits, so monitor your usage.

Scraping Limits per Target

Target Type	Posts Scraped	Comments Scraped	Google Pages
Facebook Page	50 posts	100 comments	-
Instagram Account	50 posts	-	-
Keyword Search	Up to 150 results	-	3 pages x 50 results

5. AI Reply Suggestions

     Powered by Google Gemini AI (FREE)

    Every mention automatically gets an AI-generated professional reply suggestion. You review, edit, and copy it to post from your real social media account.

How It Works

When a new mention is scraped, the AI automatically generates a reply and saves it in the database

On the dashboard, click the yellow reply button on any mention

A modal opens showing the original post and the AI-suggested reply

Edit the reply text if needed - the textarea is fully editable

Click "Regenerate" to get a completely new reply from the AI

Click "Copy to Clipboard" then paste it on the social media platform from your real account

Reply Tone by Sentiment

Sentiment	AI Reply Tone
Positive	Warm thanks, appreciation, encourages connection
Neutral	Friendly acknowledgment, offers help
Negative	Empathetic, acknowledges concern, invites private resolution via DM/email
Offensive	Calm, professional, states facts, avoids conflict

Language Matching

The AI automatically replies in the same language as the original post. If someone posts in Arabic, the reply will be in Arabic. If in English, the reply will be in English.

Important Notes

Always review and edit the AI reply before posting - it's a suggestion, not a final answer
The system does NOT auto-post replies - you always have full control
You post replies from your real brand account on the social media platform
If the AI reply doesn't feel right, click Regenerate for a new one

6. Sentiment Analysis (Gemini AI)

Every mention is analyzed by Google Gemini AI (gemini-2.0-flash model) and classified into one of four categories:

Positive
Praise, recommendation, satisfaction, love, thanks

Negative
Complaints, criticism, dissatisfaction, problems

Neutral
Information, questions, news, no emotion

Offensive
Insults, threats, scam accusations, defamation, hate

Cost: FREE

Model: Gemini 2.0 Flash (Google's fast, free model)
Cost: $0.00 - completely free
Free tier limits: 15 requests/minute, 1,500 requests/day, 1M tokens/day
Each mention uses 2 AI calls (1 for sentiment + 1 for reply) = about 750 mentions/day on free tier
Built-in auto-retry (up to 3 attempts) for reliability
Get your free key at: aistudio.google.com/apikey

7. n8n Workflow

The n8n workflow is the automation engine that runs every 30 minutes.

Workflow Nodes (6 nodes)

#	Node	What It Does
1	Every 30 Minutes	Schedule trigger - starts the workflow automatically
2	Get Active Targets	Calls your API to get the list of keywords/pages to monitor
3	Prepare Apify Jobs	Converts each target into an Apify scraping job with the right parameters
4	Run Apify Scraper	Calls Apify's API to scrape Facebook/Instagram/Google for each target
5	Normalize Results	Converts different Apify output formats into a unified mention format
6	AI Sentiment + Save	Sends each mention to your PHP API, which calls Gemini AI for sentiment + reply, then saves to database

Apify Actors Used

apify~google-search-scraper - For keyword searches across Facebook, Instagram, X, TikTok, LinkedIn via Google
apify~facebook-posts-scraper - For scraping specific Facebook pages (posts + comments)
apify~instagram-scraper - For scraping Instagram profiles (posts)

Apify Free Tier

Free credits: $5/month
Each scraping run costs ~$0.01-0.10 depending on number of results
With 3-5 targets running every 30 min = ~$3-5/month (fits in free tier)
Monitor your usage at: console.apify.com/billing
To reduce costs: lower the frequency to every 60 min, or reduce active targets

How to Update the Workflow

Go to your n8n dashboard
Delete the old workflow
Click Import from file and upload the new n8n-workflow.json
Make sure it's activated (toggle in the top right)
Run it manually once to test by clicking "Execute Workflow"

8. API Reference

Base URL: https://social.wosuol.com/api.php

Public Endpoints (No Auth)

Endpoint	Method	Description
?action=stats	GET	Returns total, risk, pending counts + sentiment/platform breakdowns
?action=get_targets	GET	Returns all active monitoring targets (n8n reads this)
?action=mark_handled	POST	Mark a mention as handled. Body: `id=123`
?action=delete_mention	POST	Delete a single mention. Body: `id=123`
?action=delete_all_mentions	POST	Delete ALL mentions and reset auto-increment
?action=generate_reply	POST	Generate/regenerate AI reply for a mention. Body: `id=123`
?action=add_target	POST	Add monitoring target. Body: `target_type=keyword&target_value=test`
?action=delete_target	POST	Delete target. Body: `id=5`
?action=toggle_target	POST	Toggle target active/inactive. Body: `id=5`

Protected Endpoints (Require `X-Api-Key` header)

Endpoint	Method	Description
?action=process_mention	POST	Insert 1 mention + auto AI sentiment + auto AI reply. JSON body with platform, author_name, post_content, post_url
?action=process_batch	POST	Insert multiple mentions at once. JSON array body.
?action=test	GET	Test API connection - shows Gemini AI, database, and curl status

Example: Insert a Mention via API

curl -X POST \
  -H "X-Api-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "Facebook",
    "author_name": "John Doe",
    "post_content": "This product is amazing!",
    "post_url": "https://facebook.com/post/123",
    "keyword_matched": "brand name"
  }' \
  https://social.wosuol.com/api.php?action=process_mention

Response:

{"success": true, "id": 45, "sentiment": "Positive", "has_reply": true}

Example: Test Connection

https://social.wosuol.com/api.php?action=test&api_key=your-secret-key

Response shows: Gemini status, API key status, model name, DB connection, curl availability.

9. Troubleshooting

Common Issues

"Could not generate reply" or "Sentiment is always Neutral"

Test your Gemini key: visit api.php?action=test&api_key=your-key
Check that GEMINI_API_KEY is set in config.php
Make sure it's not empty: define('GEMINI_API_KEY', 'AIzaSy...');
The system auto-retries up to 3 times. If Gemini is temporarily down, try again in a minute.
Free tier limit: 15 requests/minute. If you're processing many mentions at once, some may fail and retry automatically.

"n8n workflow shows 404 error on Apify"

Make sure actor names use tilde (~) not slash: apify~google-search-scraper not apify/google-search-scraper

"Dashboard shows no data"

Check if n8n workflow is activated (toggle in top-right of n8n)
Check n8n execution history for errors
Make sure you have active targets in the Config panel
Test API manually: visit api.php?action=stats

"Only getting ~20 results"

Make sure you're using the latest n8n-workflow.json (v3.0 with increased limits)
Add more targets: more keywords, more Facebook pages, more Instagram accounts
Each keyword now searches across 5 platforms (Facebook, Instagram, X, TikTok, LinkedIn)
Results depend on how much content exists online for your search terms

"Apify credits running out"

Reduce scan frequency from 30 min to 60 min in n8n
Reduce number of active targets
Temporarily disable some targets with the toggle switch
Monitor usage at: console.apify.com/billing

"Reply button not working"

Make sure the suggested_reply column exists in your database. Run:
ALTER TABLE social_mentions ADD COLUMN suggested_reply TEXT DEFAULT NULL AFTER keyword_matched;
Check that your Gemini API key is working (test endpoint)

"Duplicate mentions appearing"

The API checks post_url for duplicates. If Apify returns posts without URLs, duplicates may occur. This is normal for Google search results.

"Database connection failed"

Check config.php → DB_HOST, DB_NAME, DB_USER, DB_PASS. On Hostinger, the host is usually localhost.

Configuration File: config.php

Setting	Description
`DB_HOST, DB_NAME, DB_USER, DB_PASS`	MySQL database credentials (from Hostinger)
`GEMINI_API_KEY`	Your Google Gemini API key (free from aistudio.google.com)
`GEMINI_MODEL`	AI model to use. Default: `gemini-2.0-flash` (free, fast)
`APIFY_TOKEN`	Your Apify API token (from console.apify.com)
`API_SECRET_KEY`	Secret key for protected API endpoints. Used in n8n X-Api-Key header.

Social Listener v3.0 · Part of Wosuol System · AI by Google Gemini

Back to Dashboard