Meta Ads (Facebook / Instagram)

Priority: 2

Overview

Meta covers social prospecting and retargeting for all verticals. Accounts are provisioned under Kobi’s parent Business Manager (BM) using Meta’s official 2-Tier Business Manager solution — one child BM per client (ADR 0003). Clients never own ad accounts; they consent via portal OAuth and retain Page/IG assets.

Account model (concluded — ADR 0003)

Element	Approach
Parent BM	Kobi agency BM — extended credit, business verification (PRE-2, PRE-8), pays Meta
Per tenant	Child BM created via 2-Tier API under parent
Automation identity	Admin system user inside each child BM — long-lived token in Secret Manager (per tenant)
Client consent	Facebook Login for Business in portal — user token + shared Page required to create child BM
Naming	Child BM / ad account: `kobi_{tenant_slug}_meta`
Fallback	Single parent BM + up to 5 API ad accounts only until PRE-10 (2-Tier access) is granted

Why 2-Tier for every client (not only client #6+)

Meta limits API-created ad accounts to 5 per single BM (POST /{business_id}/adaccount). The scalable pattern is child BM per client, each with its own ad account — not five ad accounts on one BM.

Production: Use 2-Tier from client #1 once PRE-10 is active — one code path, no separate “pilot BM architecture.”

Development: Test 2-Tier directly in app Development mode (~2 child BMs typical until app review) — no need for a dedicated single-BM test harness for ≤5 clients.

Fallback: If PRE-10 is still pending, temporarily create ad accounts on the parent BM (system user) for up to five tenants; migrate to child BMs when 2-Tier access lands.

Token model — what uses which credential

Action	Token	Notes
Create child BM	Client user access token (from OAuth)	`POST /{parent_bm_id}/owned_businesses` — not parent system user (setup guide)
Create child system user	Parent or child BM admin context per Meta flow	Then generate long-lived system user token
Create ad account, pixel, campaigns, CAPI	Child BM system user	Day-to-day Marketing API
Share parent line of credit to child	Parent BM admin	Onboard at scale
Fallback: ad account on parent BM	Parent BM system user	Only when 2-Tier APIs unavailable

2-Tier onboarding flow (summary)

Client accepts ToS + data sharing in Kobi portal.
Connect Meta & Instagram — Facebook Login for Business → client picks Facebook Page (+ linked IG).
Backend: POST /{parent_bm_id}/owned_businesses with user token, shared_page_id, child BM name — owned_businesses.
Create Admin system user in child BM — System users.
POST /{child_bm_id}/adaccount + spend_cap from plan — Ad account.
Pixel, CAPI, promote_pages, catalog (SKU), offline event set — all via child system user.

Detail: provisioning spec §5 / §5b.

By default the client does not access the child BM UI; Kobi operates it agency-managed (2-Tier overview).

Access & API readiness

Requirement	Link / ID
2-Tier program access	PRE-10 — Meta rep (platform access)
Marketing API tiers	Limited → Full (rate limits)
App permissions	`ads_management`, `ads_read`, `business_management`, Page/IG scopes — cross-check §4
Extended credit on parent BM	PRE-2
Kobi entity business verification	PRE-8

Onboarding checklist (2-Tier path)

Client Connect Meta & Instagram (OAuth) — required for child BM + Page/IG
Create child BM (owned_businesses)
Create child system user + store token
Create ad account in child BM + spend_cap from plan_id
Pixel + vertical event template + CAPI relay
Link Page + IG to ad account (promote_pages, instagram_accounts)
Partner-invite fallback if OAuth asset share fails
Catalog (ecommerce SKU), offline event set (CRM SKU)
Domain verification — client DNS if required for optimization events

Not required: client as ad account owner, client BM admin, client payment method on Meta.

Official Meta documentation (sources)

Topic	URL
2-Tier BM solution	https://developers.facebook.com/docs/marketing-api/2tier-bm-solution/
Setup child BM	https://developers.facebook.com/docs/marketing-api/2tier-bm-solution/guides/setup-cbm/
Onboard at scale	https://developers.facebook.com/docs/business-sdk/common-scenarios/onboard-at-scale/
`owned_businesses`	https://developers.facebook.com/docs/marketing-api/reference/business/owned_businesses/
System users	https://developers.facebook.com/docs/marketing-api/system-users
Ad account API	https://developers.facebook.com/docs/marketing-api/reference/ad-account
Marketing API overview	https://developers.facebook.com/docs/marketing-apis
Facebook Login for Business	https://developers.facebook.com/docs/facebook-login/facebook-login-for-business/
Ad account limits (Help Center)	https://www.facebook.com/business/help/1026272311098874

Internal: ADR 0003 · B1 blocker

Collaborative Ads (CPAS) — Phase 2

Not standard owned-catalog ads. Phase 2 core track — marketplace shares catalog segment; campaigns use catalog_segment_id; measurement via shared-item metrics. Marketplace onboarding (Trendyol, Hepsiburada, …) API vs manual TBD.

Full spec: Meta CPAS (Collaborative Ads)

Feed / catalog

Product catalog synced from feed service
Match rates monitored; catalog errors block dynamic ads launch

Conversion tracking

Method	Use case
Meta Pixel (browser)	Standard events; declining reliability — pair with CAPI
Conversions API (CAPI)	Primary server-side; dedupe with `event_id`
Offline conversions	CRM events uploaded to offline event set
EMQ	Event Match Quality monitored in dashboard

First-party readiness:

Use client subdomain CAPI endpoint or Kobi-hosted relay
Pass hashed email/phone per Meta guidelines

Data to GA4

URL tags with dynamic macros: utm_campaign={{campaign.id}}, utm_content={{ad.id}}, utm_source={{site_source_name}} — UTM spec
GA4 attributed via UTMs + fbclid; join campaign ID first (not campaign name)
Cross-check: Meta vs GA4 within tolerance bands in reporting

Agent capabilities

Campaign / ad set / ad creation (ASC, prospecting, retargeting templates)
Audience application from plan (custom, lookalike specs — creation may need data minimums)
Budget pacing within guardrails
Creative rotation per approved assets only

ADR 0004: Kobi does not publish organic posts to client Page/IG feeds. No pages_manage_posts OAuth scope.

Pattern	In scope?	Notes
Standard paid ads (image/video/carousel)	✅	Approved creative assets from sibling module
Dark / unpublished post as ad creative	✅	Engagement/traffic objectives without feed visibility
Boost / promote existing organic post	✅	Client (or their team) published the post; Kobi runs paid promotion
Organic feed publishing / social calendar	❌	Out of scope — paid media module only

Human touchpoints

OAuth / Page admin verification (client)
Ad policy disapprovals (health, housing, credit special categories)
Special Ad Categories selection
Agency billing profile change (Kobi ops only — not client)

Compliance notes

Special Ad Categories (exact list): HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES (replaced CREDIT in Jan 2025), ISSUES_ELECTIONS_POLITICS. Health and schools/education are not Special Ad Categories by default — campaigns declare special_ad_categories: NONE unless the ad concerns those topics.
Every campaign must set special_ad_categories + special_ad_category_country when applicable.
EU note: social-issue/electoral/political ads are banned in the EU (TTPA, since Oct 2025).

Dependencies

GA4 baseline for landing measurement
CRM → CAPI pipeline for offline events
PRE-10 for production 2-Tier