Meta overview#

Facebook and Instagram are where many businesses win their leads — and where money quietly leaks: forms that fail, pages that reject leads, campaigns that spend without producing. Zodiac Tech CRM connects your Meta world (pages, lead forms, ad accounts) directly to the CRM, so a form submission becomes a lead with an owner in seconds.

This page is the map. The other marketing guides go deep on each area.

Who this is for#

• Business owners (clients) — see what ads produce without asking the agency for a spreadsheet.

• Admins — connect Meta, choose pages and forms.

• Ad specialists — run campaigns, creatives and QA.

• Difficulty: Easy

• Time: 8 minutes to understand the layout

• Prerequisites: None to read. Connecting needs admin access and a Meta login with access to your business's pages.

The three surfaces#

Meta work touches three different panels. Knowing which one you are in saves confusion:

If you are a client: your day-to-day is the tenant CRM's Ads group — [Ads overview dashboard, Campaign drafts, Creative approvals]. If an agency runs your ads, the agency console is their workspace; you will see the outputs in your CRM and receive creatives for approval.

What the connection gives you#

1. Lead delivery — Facebook/Instagram lead-form submissions land in the CRM as leads with source, campaign, ad and form details attached (see Meta lead capture pipeline).
2. Ad results next to sales results — the Ads dashboard shows 30-day spend, impressions, clicks, leads, cost per lead, qualified leads, appointments, sales and ROAS, per campaign. Numbers are deterministic database aggregates, not estimates.
3. A governed workflow — campaigns are drafted in the CRM, approved by the client, QA-checked and launched paused by a QA reviewer (see Campaigns).
4. Honest health monitoring — connections are pinged every 6 hours, and a scanner flags problems (cost spikes, dead connections, zero-lead campaigns) so nothing silently breaks (see Ads health & needs attention).

The tenant Ads group (what you see in /admin)#

Steps: see what your ads produced (client)#

1. Open Ads → Overview.

Expected result: last-30-day numbers: what was spent, how many leads arrived, what they cost, and how many became appointments or sales. Until Meta is connected, a friendly empty state explains how to connect.

2. Scroll to the campaign table and open a lead list filter for a campaign to see the actual people.

Expected result: you move from "the ads cost X" to "here are the leads and what they became".

Steps: connect Meta (admin)#

1. Go to Settings → Connections, find the Meta source, and click Connect.
2. Sign in to Facebook and accept the permissions (this grants access to your Pages, their engagement, and ad management for the pages you pick).
3. Back in the CRM, Select Page from the pages the system found, and repeat for the ad account where your campaigns live.

Expected result: the connection turns active; lead forms become available for selection; health checks begin. Full detail in OAuth & permissions.

Expected result#

Announcements of where everything lives: your team connects and monitors, the agency runs ads, and the numbers land where the work happens. No spreadsheets, no copy-pasting leads.

Common mistakes#

• Trying to add Meta credentials as a client. You cannot and should not — the platform app handles authentication; you only grant permission to your Pages.
• Connecting with a personal Facebook account that lacks Page access. Ask a Page admin to grant access first.
• Confusing the Ads Overview with Meta Ads Manager. The CRM shows your agreed metrics and CRM outcomes; Ads Manager remains Meta's own tool.
• Running campaigns outside the workflow. If a campaign was never drafted in the CRM and QA-passed, it cannot be launched through the agency console — that gate is deliberate.

Troubleshooting#

Technical details#

• Platform app: App\Settings\MetaSettings — app id/secret (encrypted) and environment (development/production), configured in Super Admin → Settings → Meta Developer. Tenants never store credentials for the OAuth flow; per-connection credentials exist only for backwards compatibility.
• Tenant connect: App\Http\Controllers\OAuthConnectionController (providers meta / instagram / tiktok / linkedin / google_ads / microsoft_ads; state-verified callbacks). Connection data: lead_source_connections.credentials (page list, chosen page, token).
• Ingest: App\Http\Controllers\InboundWebhookController → App\Services\LeadSources\MetaConnector → MetaLeadFormService (field mapping + form allowlist).
• Health/sync: leadhub:meta-health every 6 hours; leadhub:sync-meta-ads daily 04:30 (last 30 days → MetaInsight); ops scan leadhub:meta-ops-scan every 30 minutes + leadhub:meta-ops-brief 07:15.
• Metrics: App\Services\MetaAds\MetaAdsMetrics (spend, CPL, CPL-qualified, appointments, sales, revenue, ROAS), attribution via leads.meta_ad_id → meta_ads → meta_adsets → meta_campaigns.

Related guides#

• OAuth & permissions — the connection walkthrough.
• Meta lead capture pipeline — how a form submission becomes a lead.
• Campaigns — the draft → approve → QA → launch workflow.
• Agency panel (Meta Ops) — the team running ads for you.
• Ads health & needs attention — the monitoring layer.