GBP Post Writer

interface GbpPostWriterInput {
  tenantId:  string;
  month:     string;           // e.g. "2026-04" — used to scope seasonal relevance
  postType:  'whats-new' | 'offer' | 'event';
  topic?:    string;           // optional — if omitted, agent selects topic from RAG + seasonal context
 
  // Required when postType === 'offer'
  offerDetails?: {
    title:     string;         // e.g. "Spring Cleaning Special"
    discount:  string;         // e.g. "20% off all services"
    coupon?:   string;         // e.g. "SPRING20"
    startDate: string;         // ISO date
    endDate:   string;         // ISO date
  };
 
  // Required when postType === 'event'
  eventDetails?: {
    title:  string;
    date:   string;            // ISO date
    time?:  string;            // e.g. "10:00 AM – 2:00 PM"
    url?:   string;            // event registration or info URL
  };
}

interface GbpPostWriterOutput {
  bodyText:       string;                   // max 1,500 characters — hard enforced
  characterCount: number;
  callToAction: {
    type: 'book' | 'order' | 'buy' | 'learn-more' | 'sign-up' | 'call';
    url:  string;
  };
  photoSuggestion: string;                  // description of ideal photo for this post
  postType:        'whats-new' | 'offer' | 'event';
  topicUsed:       string;                  // the topic chosen (useful when input topic was omitted)
}

bodyText:
Spring is here — and so is your chance to finally tick off those home maintenance jobs you've
been putting off.

Throughout April, Apex Home Services is offering 20% off all gutter cleaning, exterior washing,
and driveway sealing bookings. No job too small. Fully insured, locally owned, and operating
across the greater Melbourne metro area since 2011.

Why April? It's the perfect window before winter — we've seen more callouts for blocked gutters
and water damage in June and July than any other time of year. A clean-out now costs a fraction
of what repairs cost later.

📅 Book before 30 April to lock in your discount. Use code SPRING20 at checkout.

Slots are filling fast — our April calendar is already 60% booked. Don't leave it too late.

---
callToAction:
  type: "book"
  url: "https://apexhomeservices.com.au/book"

photoSuggestion:
"Before/after photo of a freshly cleaned gutter or driveway. Natural light, realistic setting.
Avoid stock photography — a real job site photo performs significantly better on GBP."

You are a local SEO content writer creating a Google Business Profile post for a small or
medium-sized business. Your goal is to write a post that drives real customer actions —
bookings, calls, visits — not just impressions.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

TENANT SETTINGS:
{{TENANT_SETTINGS}}

KNOWLEDGE BASE CONTEXT (previous posts, offer details, upcoming events):
{{RAG_CONTEXT}}

POST BRIEF:
{{BRIEF}}

You are writing a {{POST_TYPE}} post for {{MONTH}}.

Rules you must follow:
1. Body text must be 1,500 characters or fewer — this is a hard platform limit. Count carefully.
2. Write in the business's voice — not formal corporate, not startup-casual. Match the tone
   described in the client context.
3. Be specific: name the actual service, actual discount amount, actual dates. Vague posts
   perform poorly on GBP.
4. Local signals matter — mention the service area or city naturally if it fits. Google uses
   GBP posts as local relevance signals.
5. Every post needs genuine urgency or value — why should someone act today? Answer that
   question in the first 2 sentences.
6. Do not mention competitor business names under any circumstances.
7. Do not make misleading claims — if the offer has conditions, state them clearly.
8. Do not use prohibited words from tenant settings.
9. Emoji usage: 1–2 relevant emoji are acceptable for What's New and Offer posts if the brand
   voice is conversational. Zero emoji for formal/professional brands.
10. End with a clear action signal — the body text should lead naturally into the CTA button.

For OFFER posts: include the discount, coupon code (if provided), and both start and end dates.
For EVENT posts: include the event title, date, time, and registration URL if provided.
For WHAT'S NEW posts: focus on a specific service update, seasonal highlight, or business news.

Output as JSON matching the GbpPostWriterOutput schema.

# Google Business Profile Post Guide
 
## What GBP Posts Are For
GBP posts appear on a business's Knowledge Panel in Google Search and Maps. They are read by
customers who have already found the business — the audience is warm. The goal is to convert
interest into action: a booking, a call, a visit.
 
## Post Types and When to Use Each
 
### What's New
Use for: service announcements, seasonal tips, business updates, recent achievements, community
involvement. Avoid: generic "we're open" posts that add no value.
Character limit: 1,500. Recommended: 300–600 characters for best readability.
 
### Offer
Use for: time-limited discounts, seasonal promotions, new customer deals.
Required fields in Google: offer title, start date, end date. Coupon code is optional but
improves tracking.
Always state the discount clearly. "Up to X% off" requires a qualifying minimum — if there is
no minimum, say "X% off" directly.
 
### Event
Use for: workshops, open days, community events, webinars, in-store events.
Required fields: event title, start date/time, end date/time.
Include the registration or info URL wherever possible.
 
## Writing for GBP: What Works
 
**Open with the value, not the brand name.**
Weak: "Apex Home Services is pleased to offer..."
Strong: "20% off all gutter cleaning this April — book before slots fill up."
 
**Be local.** Mention the suburb, city, or service area once. Google treats this as a local
relevance signal and customers trust businesses that know their area.
 
**Use real specifics.** "Over 200 5-star reviews" beats "highly rated". "Available Monday to
Saturday, 7 AM to 5 PM" beats "flexible scheduling".
 
**Create genuine urgency.** Date-limited offers, capped availability, and seasonal timing are
all legitimate urgency signals. Never fabricate scarcity.
 
## CTA Type Selection Guide
| Post goal | Best CTA type |
|---|---|
| Book an appointment | `book` |
| Purchase a product | `buy` or `order` |
| Event registration | `sign-up` |
| Learn about a service | `learn-more` |
| Call for a quote | `call` |
 
## Photo Guidance
GBP posts with photos receive 3–5× more views than text-only posts.
- Real job site photos outperform stock images significantly
- For offers: show the service being performed or the product
- For events: show the venue or a previous event
- For What's New: show the team, the location, or the updated service