Social

The Social module is Lubb's Meta (Facebook/Instagram) ad management workspace: it connects a tenant's Meta ad accounts, lets marketers build and launch campaigns, ad sets and ads without leaving the ERP, generates ad creative with AI, and captures/exports leads from Facebook Lead Ads. It's used by marketing and sales-ops teams running paid social for a tenant (e.g. Telecloud, Movie Magic), plus downstream systems (a CRM) that pull in the leads it collects.

What you can do

• Connect Meta ad accounts — OAuth-connect one or more Facebook ad accounts per tenant, store per-tenant Meta App ID/Secret, and see each account's sync status (Settings + Meta connection screens).
• Browse campaigns, ad sets and ads — grids of campaigns with objective/budget, drill into a campaign's ad sets, and into an ad set's ads, including per-ad lead counts.
• Pause/activate campaigns — change a single campaign's status or bulk-update many at once (ACTIVE/PAUSED/DELETED), or "Make live" a whole campaign tree (campaign + all its ad sets + all its ads) in one click.
• Build ad sets with full targeting — a composer with live Meta lookups: detailed-targeting (interests/behaviours) autocomplete, geo search, language search, custom/lookalike/saved audiences, pixels, and a live audience-size (reach) estimate; can create a brand-new campaign inline.
• Check ad-account billing/verification status — see whether a funding source and verification are in place before launching, with deep links to Meta's own billing/verification pages.
• Generate AI ad creative — describe an ad in a prompt and get back an AI-generated image (Gemini "Nano Banana"), plus a conversational chat mode to iteratively edit/combine up to 14 reference images, matching ad copy (primary text/headline/description), AI web research on competitor pricing, and AI-suggested Meta audience targets validated against Meta's live targeting search.
• Create Lead Ads end-to-end — build a Facebook lead-generation form (custom questions, privacy policy, context card, thank-you page, optional "connect in Messenger"), or create form + campaign + ad set + creative + ad together in a single "full lead ad" flow.
• Manage lead forms — list Pages and their linked Instagram accounts, import/sync existing lead forms from Meta, view a form's live definition, archive forms, and pull submitted leads per form.
• Auto-reply to Instagram DMs — configure a per-Page/IG-account auto-responder that answers unattended Instagram inboxes once per sender per 24 hours.
• Reporting & exports — performance dashboards (blended and by campaign), CSV export of daily insights, and scheduled/ad-hoc email reports.
• POPIA compliance tools — export all of a tenant's Social data, request full tenant data deletion, and record consent.
• ERP-linked dashboard cards — for accounts mapped to a linked ERP, see ERP lead counts and sales totals alongside Meta lead-form counts.

Common tasks

1. Connect a Meta ad account — In Settings, enter the tenant's Meta App ID/Secret (or rely on server defaults), then use the Meta connection screen to start OAuth. On callback, Lubb exchanges the code for a long-lived token, discovers the user's ad accounts, and stores them; existing accounts are refreshed (not duplicated) on reconnect.
2. Launch a campaign with a new ad set — Open the ad set composer, either pick an existing campaign or define a new one inline (objective, budget, special ad categories), set optimization goal/billing event, build the targeting spec (audiences, geo, interests via the live search), check the reach estimate, then submit — the ad set (and campaign, if new) is created on Meta and mirrored locally.
3. Make a campaign live — From a campaign's action menu, use "Make live" (POST /campaigns/{campaign_id}/publish-live) to flip the campaign and every one of its ad sets and ads to ACTIVE in one call; per-item failures are reported without blocking the rest.
4. Generate an AI ad creative — In the AI Ad Generator, type a prompt describing the ad; Lubb calls Gemini to produce a preview image and (optionally) ad copy. Refine it conversationally (attach/edit images, keep aspect ratio), then upload the chosen image to Meta's image library to get the hash used when creating the ad.
5. Build and launch a lead ad — Use the Lead Ads "Create" flow to define the form's questions, privacy policy and thank-you page alongside the campaign name/budget, ad-set targeting, and creative message/image/CTA; one submit creates the form, campaign, ad set, creative and ad together (all start PAUSED).
6. Export or report on leads/performance — Sync lead forms from Meta to pull in submitted leads, view them per form, or export daily insights as CSV (/reports/export/csv); external systems pull leads incrementally via the service-to-service /leads/export endpoint.

Data model

• MetaAccount — a connected Facebook ad account: encrypted access token, currency, timezone, sync status.
• Campaign — mirrors a Meta campaign (objective, status, daily/lifetime budget) under an ad account.
• AdSet — mirrors a Meta ad set (targeting spec, budget, optimization goal/billing event) under a campaign.
• Ad — mirrors a Meta ad (creative reference, status) under an ad set.
• LeadGenForm — a Facebook lead-gen form (questions, privacy policy, thank-you page) plus which campaign/ad set/ad it's attached to.
• Lead — a submitted lead captured from a lead form (contact fields, field_data, source form/ad/campaign), exported to external CRMs.
• InsightsDaily — daily performance metrics (spend, impressions, clicks, conversions, CTR/CPC/CPM/ROAS, reach, frequency) per account/entity, feeding dashboards and CSV export.
• Report — a scheduled or ad-hoc report definition (recipients, schedule, template).
• IgAutoReplyConfig — per-Page/Instagram-account auto-reply settings (message, enabled flag, stored Page token).
• AuditLog — records every mutating action (status changes, ad set/lead form creation, syncs, POPIA actions) with actor, IP and details.

Configuration & integrations

• Meta Graph API (Facebook/Instagram Ads) — the core integration. OAuth app credentials (App ID/Secret, redirect URI) can be set per tenant in Settings or fall back to server-wide env vars; the OAuth scope requested covers ads management/read, insights, Pages, lead retrieval, business management, and Instagram/Page messaging. Access tokens are encrypted at rest and exchanged for long-lived (60-day) tokens.
• Google Gemini — used for AI ad image generation/editing (Nano Banana image model), ad copywriting, competitor price research (with Google Search grounding), and audience-targeting suggestions. API key and model names are configurable via a provider settings grid or GEMINI_API_KEY/GEMINI_IMAGE_MODEL/GEMINI_TEXT_MODEL env vars.
• Instagram Messaging webhook — POST /webhooks/instagram receives DM events (signature-verified against the Meta app secret); requires the Meta App Dashboard to have instagram_manage_messages (Advanced Access), the webhook subscribed to messages, and each IG account's "Allow access to messages" toggle on.
• Linked ERP accounts — specific ad accounts can be mapped to a linked Frappe/ERPNext site (settings.erp_by_account) so the dashboard can show that ERP's lead count and sales totals alongside Meta figures.
• Lead export token — a shared-secret (lead_export_token in app_settings) authenticates trusted internal callers (e.g. a CRM sync job) against /leads/export, independent of normal tenant JWT auth.

API reference

Meta connection & accounts (/meta)

• GET /meta/config, PUT /meta/config — read/save the tenant's Meta App ID/Secret/redirect URI.
• GET /meta/connect — get the Meta OAuth authorization URL.
• GET /meta/callback — OAuth callback: exchanges code for tokens and discovers ad accounts.
• GET /meta/accounts — list the tenant's connected ad accounts.
• DELETE /meta/accounts/{account_id} — soft-delete an ad account.
• GET /meta/accounts/{account_id}/ads — locally synced ads for an account.
• GET /meta/sync-status — sync status across all accounts.
• POST /meta/accounts/{account_id}/sync, POST /meta/accounts/sync-all — trigger campaign/insights/lead-form sync.

Campaigns (/campaigns)

• GET /campaigns — list campaigns (optionally by account).
• GET /campaigns/{campaign_id}/ads, /adsets, /adsets/{adset_id}/ads — drill-down listings.
• PUT /campaigns/{campaign_id}/status, PUT /campaigns/bulk/status — change campaign status (single/bulk).
• POST /campaigns/{campaign_id}/publish-live — activate a campaign and everything under it.

Ad sets (/adsets)

• GET /adsets/targeting-search/{account_id}, /geo-search/{account_id}, /locale-search/{account_id} — live Meta autocomplete for interests/behaviours, locations, languages.
• GET /adsets/custom-audiences/{account_id}, /saved-audiences/{account_id}, /pixels/{account_id} — list audiences and pixels for targeting.
• GET /adsets/account-status/{account_id} — billing/verification status.
• POST /adsets/reach-estimate/{account_id} — audience-size/delivery estimate.
• POST /adsets/{account_id} — create an ad set (optionally with an inline new campaign).

AI ad generation (/ai-ads)

• POST /ai-ads/generate/{account_id} — prompt to image + optional ad copy (preview only).
• POST /ai-ads/chat/{account_id} — conversational image generation/editing.
• POST /ai-ads/pricing-research/{account_id} — AI web research on 3 competitor prices + average.
• POST /ai-ads/target-suggestions/{account_id} — AI-suggested targeting terms resolved against live Meta audiences.
• POST /ai-ads/upload-generated/{account_id} — upload a chosen generated image to Meta's image library.

Lead ads (/lead-ads)

• GET /lead-ads/pages/{account_id} — Pages with linked Instagram accounts.
• POST /lead-ads/sync/{account_id} — import lead forms from Meta.
• GET /lead-ads/forms/{account_id} — list locally stored lead forms with usage/lead counts.
• POST /lead-ads/forms/{account_id}/{page_id} — create a lead form.
• POST /lead-ads/forms/{account_id}/{page_id}/{form_id}/archive — archive a form.
• GET /lead-ads/forms/{account_id}/{form_id}/leads, /details — fetch a form's leads / live definition.
• POST /lead-ads/create/{account_id} — create form + campaign + ad set + creative + ad in one call.

Lead export (/leads, service-to-service)

• GET /leads/export — cursor-paginated export of leads for external consumers, authenticated by a shared token header.

Instagram messaging (/webhooks/instagram, /ig-autoreply)

• GET/POST /webhooks/instagram — Meta webhook verification and DM event delivery.
• GET /ig-autoreply/configs, PUT /ig-autoreply/configs/{page_id} — list/configure per-Page auto-reply.
• POST /ig-autoreply/configs/{page_id}/test — send a test auto-reply.

Reports & dashboard (/reports, /dashboard)

• GET /reports/export/csv — CSV export of daily insights.
• GET /reports/performance, /reports/performance/campaigns, /reports/dashboard — aggregated performance summaries.
• GET /reports/campaign/{campaign_id}/insights — insights for one campaign.
• POST /reports, GET /reports — create/list scheduled or ad-hoc reports.
• GET /dashboard/stats, /dashboard/erp-leads, /dashboard/lead-form-leads — dashboard summary cards.

Compliance (/compliance)

• GET /compliance/export — export all tenant data (POPIA Section 23).
• POST /compliance/delete — request full tenant data deletion (POPIA Section 24, owners only).
• POST /compliance/consent — record POPIA consent.