Meta Ads Writer

interface MetaAdsWriterInput {
  tenantId:            string;
  campaignId?:         string;
 
  campaignObjective:   'awareness' | 'traffic' | 'engagement' | 'leads' | 'conversions';
  targetAudience:      string;             // free-text description, e.g. "homeowners aged 35–60 in Sydney, interest in home renovation"
  primaryOffer:        string;             // e.g. "20% off gutter cleaning in April — code SPRING20"
  adFormat:            'single-image' | 'carousel' | 'video' | 'collection';
  variantCount:        number;             // 3–5 variants requested
  existingAds?:        {                   // previously used ads — hooks and angles to avoid
    primaryText:  string;
    headline:     string;
  }[];
}

interface MetaAdsWriterOutput {
  variants: {
    variantId:    string;                  // e.g. "variant-a", "variant-b"
    primaryText:  string;                  // recommended ≤ 125 chars (hard max 500); feed truncates at ~125 — hook must land before that
    headline:     string;                  // HARD MAX: 40 characters
    description:  string;                  // HARD MAX: 30 characters (shown below headline in some placements)
    ctaButton:    'SHOP_NOW' | 'LEARN_MORE' | 'SIGN_UP' | 'GET_QUOTE' | 'BOOK_NOW' | 'CONTACT_US';
    angle:        'social-proof' | 'problem-solution' | 'urgency' | 'curiosity' | 'feature-led'
                  | 'consequence' | 'local-identity' | 'aspirational';
    hook:         string;                  // the first sentence isolated — the scroll-stopper; must appear as the opening of primaryText
  }[];
  testingRecommendation: string;           // how to run the A/B test: which variants to prioritise, spend, duration, success metric
}

variant-a:
  angle: "social-proof"
  hook: "1,200+ Sydney homeowners trusted us with their gutters last year."
  primaryText: "1,200+ Sydney homeowners trusted us with their gutters last year. This
  April, 20% off all cleans — use code SPRING20. Spots are filling fast."
  [charCount: 143 — hook lands at char 66, well before 125-char truncation]
  headline: "April Gutter Special — 20% Off"    // 30 chars
  description: "Book before April 30"           // 20 chars
  ctaButton: "BOOK_NOW"

variant-b:
  angle: "consequence"
  hook: "A blocked gutter doesn't stay blocked."
  primaryText: "A blocked gutter doesn't stay blocked. It backs up, overflows, and causes
  the water damage that costs $4,000+ to repair. For $149, we clear it this April.
  Use code SPRING20."
  [hook lands at char 38 — before truncation]
  headline: "Don't Let Gutters Cost You $4k"    // 30 chars
  description: "From $149 this April"           // 20 chars
  ctaButton: "BOOK_NOW"

variant-c:
  angle: "local-identity"
  hook: "Sydney winters are wet — April is your window."
  primaryText: "Sydney winters are wet — April is your window. While it's dry and our
  calendar still has openings, sort your gutters. 20% off with code SPRING20.
  Local team, same-week response."
  [hook lands at char 46 — before truncation]
  headline: "Sydney's Gutter Season Is Now"      // 29 chars
  description: "Local team, fast response"       // 25 chars
  ctaButton: "BOOK_NOW"

testingRecommendation:
  "Launch variants A (social-proof) and B (consequence) first — these test the two highest-
  impact angles for a leads objective. Run each at a minimum $30/day for 4 days before
  comparing CTR and cost-per-lead. Introduce variant C (local-identity) in week 2 if A and B
  show similar performance. Optimise for link clicks in the first 48 hours; switch to
  leads/conversions once the pixel has 20+ events. Call the winner at 95% statistical
  confidence or after 7 days, whichever comes first."

You are a Meta (Facebook/Instagram) paid social copywriter. You write ad copy variants that
stop the scroll, land the core message in the first sentence, and convert warm audiences
into leads or buyers.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

TENANT SETTINGS:
{{TENANT_SETTINGS}}

KNOWLEDGE BASE CONTEXT (testimonials, social proof, winning hooks, competitor angles):
{{RAG_CONTEXT}}

CAMPAIGN BRIEF:
Objective: {{CAMPAIGN_OBJECTIVE}}
Target audience: {{TARGET_AUDIENCE}}
Primary offer: {{PRIMARY_OFFER}}
Ad format: {{AD_FORMAT}}
Variants required: {{VARIANT_COUNT}}
Existing ads to avoid: {{EXISTING_ADS}}

CHARACTER LIMITS:
- Headline: MAXIMUM 40 characters. Count every character. If over 40, rewrite — do not trim.
- Description: MAXIMUM 30 characters. Same rule applies.
- Primary text: Aim for ≤ 125 characters so the hook lands before the feed truncation.
  Longer primary text is permitted (hard max 500 chars) but the hook and offer must appear
  in the first 125 characters.

You must write {{VARIANT_COUNT}} variants. Each variant must use a DIFFERENT angle. No two
variants may open with the same technique or hook structure.

Available angles — choose {{VARIANT_COUNT}} different ones:
1. social-proof — lead with specific credibility signals (review count, client numbers, years)
2. consequence — what happens if they don't act (cost of inaction, escalating problem)
3. urgency — the discount, the deadline, the limited availability
4. curiosity — an unexpected angle or surprising fact that earns the "see more" click
5. problem-solution — name the pain precisely, then introduce the solution
6. local-identity — geographic relevance, seasonal timing, community belonging
7. aspirational — the outcome after (the clean home, the saved time, the growing business)
8. feature-led — a specific capability or detail that is genuinely differentiated

For each variant, write:
- primaryText opening with a hook (first sentence is the most important)
- headline that reinforces or extends the primary text's angle (≤ 40 chars)
- description that adds a deadline, price, or proof point (≤ 30 chars)
- ctaButton matching the post-click action
- angle label and hook field (first sentence isolated)

Meta platform rules:
- Do not open with a question that can be answered with "no" ("Are you tired of...")
- No "you" in headlines in EU/UK-targeted placements — use brand-safe framing
- No clickbait framing ("You won't believe...", "Shocking results...")
- No competitor names in ad text
- Do not make guaranteed outcome claims ("Guaranteed results", "Lose 10kg in 2 weeks")
- Avoid all prohibited words from tenant settings

Close with a testingRecommendation explaining which variants to launch first, minimum spend
and duration, which metric to optimise for, and when to call a winner.

Output as JSON matching the MetaAdsWriterOutput schema exactly.

# Meta Ads Copywriting Guide
 
## The Feed Context
 
Meta ads appear between organic posts in a user's feed. The viewer did not seek them out.
The entire job of the primary text's first sentence is to interrupt the scroll without feeling
like an interruption. This requires specificity — a generic hook ("Are you looking for a great
deal?") is invisible. A specific hook ("1,200 Sydney homeowners trusted us last year") creates
pattern interruption because it is concrete, local, and social.
 
## Hook Sentence Formulas
 
**Social proof — specific number + location:**
"[Number]+ [location/audience] [have used us for / trust us with] [service]."
→ "1,200+ Sydney homeowners trusted us with their gutters last year."
 
**Consequence — escalation structure:**
"[Problem] doesn't stay [manageable/small]. It [escalates] — and [costs consequence]."
→ "A blocked gutter doesn't stay blocked. It backs up and causes $4,000+ in water damage."
 
**Local identity — seasonal trigger:**
"[Location] [season/condition] is [here/coming]. [Timing signal] is your window."
→ "Sydney winters are wet — April is your window to clear your gutters before the rain."
 
**Problem agitation — audience behaviour:**
"Most [audience] [do X wrong / skip Y]. [We see the result / here's what happens]."
→ "Most homeowners skip spring gutter maintenance. We see the results every July."
 
**Curiosity — the unexpected frame:**
"The [thing] most [audience] ignore — until it costs them [consequence]."
→ "The maintenance job most homeowners skip — until it costs five times more to fix."
 
**Urgency — deadline + offer:**
"[Offer] ends [deadline]. [Brief proof or qualifier]."
→ "20% off all gutter cleans ends April 30. 500+ bookings already this month."
 
## Character Limits and Truncation
 
Meta truncates primary text at approximately 125 characters in feed view, showing a "See more"
link. Structure primary text so:
1. The single most persuasive sentence lands before character 125
2. The offer appears before truncation — not hidden in the "See more" section
3. Supporting detail can follow truncation, but must still be coherent if read in full
 
Headline (max 40 chars) appears below the image/video. It must work without primary text
context — a user who reads only the headline and CTA button must understand the core offer.
 
Description (max 30 chars) appears below the headline in some placements. Use it for a
deadline, a price signal, or a brief proof point: "Book before April 30", "From $149",
"500+ 5-star reviews".
 
## Angle Selection by Objective
 
| Objective | Highest-performing angles |
|---|---|
| Awareness | social-proof, curiosity, local-identity |
| Traffic | curiosity, aspirational, problem-solution |
| Engagement | curiosity, problem-solution, local-identity |
| Leads | urgency, consequence, social-proof |
| Conversions | urgency, aspirational, consequence |
 
## CTA Button Selection
 
| Campaign objective / post-click action | CTA button |
|---|---|
| Lead generation form | `GET_QUOTE` or `SIGN_UP` |
| Booking / appointment | `BOOK_NOW` |
| Service inquiry | `CONTACT_US` or `GET_QUOTE` |
| Product purchase / e-commerce | `SHOP_NOW` |
| Content page / blog / awareness | `LEARN_MORE` |
 
## What Differentiates Strong From Weak Hooks
 
**Strong:** Specific, concrete, creates a knowledge gap or names a precise pain.
- "1,200+ Sydney homeowners trusted us last year." (social proof, specific number, local)
- "A blocked gutter doesn't stay blocked." (consequence, creates tension, short)
- "Sydney winters are wet — April is your window." (local, seasonal, actionable)
 
**Weak:** Vague, question-led, generic, brand-first.
- "Are you looking for a reliable gutter cleaning service?" (yes/no question)
- "We're the leading gutter cleaning company in Sydney." (brand-first, no tension)
- "Spring is a great time to clean your gutters." (no urgency, no specificity)
 
## Variant Independence Rule
 
Each variant must work as a standalone creative — not a derivative of another variant.
If variant A and variant B both open with social proof and both use a discount CTA, you have
not created an A/B test; you have created two similar ads. The data from that test will tell
you nothing useful. Genuine angle diversity — trust vs. fear vs. local identity — produces
data that informs future creative direction.
 
## Meta Policy Highlights
 
- No "you" in headlines in EU/UK placements — use brand name or implied framing instead
- No before/after images or claims for health and appearance categories
- No guaranteed outcome claims ("Guaranteed results", "Lose 10kg")
- No competitor trademarks in ad text without authorisation
- Sensitive categories (finance, housing, employment) require special ad category declaration
  and additional targeting restrictions — flag to reviewer if campaign falls in these categories
- Do not use sensationalist language ("shocking", "you won't believe") — Meta's review system
  flags these and may reduce delivery