# Review Generator — Full Workflow Specification
## Module: Reputation Rocket | GHL Power Module | ReceptionistAI Suite
## Version: 1.0.0 | Authority: Genesis Build

---

## Overview

The Review Generator automates post-job Google review collection for Australian trade and service businesses. It is a composable add-on that deploys onto any GoHighLevel sub-account and runs entirely without manual effort from the business owner after initial setup.

**Pricing:** $97/mo add-on | $197/mo standalone

---

## Trigger Events

The workflow can be fired by any of the following:

| Trigger Type | Method | Notes |
|---|---|---|
| AIVA post-call webhook | Telnyx AI Assistant → Webhook URL | Fires after AI receptionist completes a call |
| GHL tag added | Tag: `review-requested` | Manual trigger or via external integration |
| ServiceM8 job completed | n8n bridge → GHL webhook | See n8n bridge section below |
| Tradify job completed | Zapier/n8n → GHL webhook | Same pattern as ServiceM8 |
| GHL pipeline stage change | GHL native trigger | Stage "Job Complete" → fires workflow |
| GHL calendar appointment marked complete | GHL native event | Calendar-driven completion |

**Duplicate protection:** Contact must NOT have tag `review-completed` OR `review-in-progress` for the trigger to fire. If either tag exists, the workflow exits immediately.

---

## Workflow 1: Review Request (RR-01)

**Name:** `RR - 01 - Review Request`
**GHL Type:** Automation Workflow
**Status on deploy:** Active
**Re-entry:** Disabled (prevents duplicate sequences for same contact)

### Step-by-Step Flow

```
TRIGGER: Tag "review-requested" added OR webhook fires
         |
         v
STEP 1: Add Tag
  - Tag: review-in-progress
  - Purpose: prevents duplicate workflow execution

         |
         v
STEP 2: Wait — Fixed Delay
  - Duration: 2 hours
  - Allows job completion to fully process; lets customer settle before outreach

         |
         v
STEP 3: Send SMS — Review Request
  - Template: RR - Review Request (see sms_templates.md)
  - From: Sub-account LC Phone number
  - Personalised with: first_name, technician_name, job_type, rating_page_url

         |
         v
STEP 4: Add Contact to Pipeline
  - Pipeline: Reputation Tracker
  - Stage: (no stage set — Workflow 2 sets stage on form submission)

         |
         v
STEP 5: Wait for Event (optional — requires GHL advanced workflows)
  - Wait for: Form submission on review_rating_form
  - Timeout: 72 hours
  - If submitted within 72h: Exit (Workflow 2 takes over)
  - If timeout reached: Exit, leave tag as review-in-progress for reporting
```

---

## Workflow 2: 5-Star Filter (RR-02)

**Name:** `RR - 02 - 5-Star Filter`
**GHL Type:** Automation Workflow
**Trigger:** Form Submission — `review_rating_form`
**Status on deploy:** Active

This workflow fires the moment a customer submits their star rating on the GHL rating funnel page. It routes positive and negative feedback to separate paths.

### Step-by-Step Flow

```
TRIGGER: Form submission — review_rating_form
         |
         v
STEP 1: Update Custom Field
  - Field: review_rating
  - Value: {{form.review_rating}} (from form submission)

         |
         v
STEP 2: If/Else Branch — Rating Check
  Condition: custom_field.review_rating >= 4

         |                              |
    YES (4 or 5 stars)           NO (1, 2, or 3 stars)
         |                              |
         v                              v
  STEP 2a: Send SMS             STEP 2e: Send Internal Email
    "Thank you! Share on          To: [owner email]
     Google: [link]"              Subject: Negative feedback received
                                  Body: Rating, customer name, job type,
         |                        technician, phone — see template below
         v
  STEP 2b: Add to Pipeline        STEP 2f: Add to Pipeline
    Stage: Review Requested         Stage: Negative Feedback

         |                              |
         v                              v
  STEP 2c: Add Tag              STEP 2g: Add Tag
    positive-feedback               negative-feedback

         |                              |
         v                              v
  STEP 2d: Remove Tag           STEP 2h: Remove Tag
    review-in-progress              review-in-progress

                                       |
                                       v
                                STEP 2i: Add Note to Contact
                                  "Negative feedback. Rating: X/5.
                                   Job: [job_type].
                                   Tech: [technician_name].
                                   Owner notified."
```

### Internal Negative Feedback Email Template

```
Subject: [ALERT] Negative feedback — {{contact.first_name}} {{contact.last_name}}

A customer submitted a rating of {{custom_field.review_rating}} out of 5 stars.

Customer: {{contact.first_name}} {{contact.last_name}}
Phone: {{contact.phone}}
Job Type: {{custom_field.job_type}}
Technician: {{custom_field.technician_name}}
Submitted: {{date}}

ACTION REQUIRED: Do NOT send this customer to Google Reviews.
Recommended: Call the customer within 24 hours to resolve their concern.

This contact has been added to the "Negative Feedback" stage in your Reputation Tracker pipeline.
```

---

## Workflow 3: Google Review Follow-Up (RR-03)

**Name:** `RR - 03 - Google Review Follow-Up`
**GHL Type:** Automation Workflow
**Trigger:** Contact tag added — `positive-feedback`
**Filter:** Contact does NOT have tag `review-completed`
**Status on deploy:** Active

Fires 48 hours after a customer gives 4 or 5 stars to prompt them to post the actual Google review (since submitting the internal rating form and posting to Google are two separate actions).

### Step-by-Step Flow

```
TRIGGER: Tag "positive-feedback" added
         |
         v
STEP 1: Wait — Fixed Delay
  - Duration: 48 hours
  - Gives customer time to post naturally before we nudge

         |
         v
STEP 2: If/Else Branch — Has review been completed?
  Condition: Contact does NOT have tag "review-completed"

         |                              |
    YES (no tag — no review yet)   NO (has tag — already done)
         |                              |
         v                              v
  STEP 2a: Send SMS             STEP 2c: Exit Workflow
    Template: RR - Review          (No action — review already posted)
    Follow-Up

         |
         v
  STEP 2b: Add Tag
    follow-up-sent
```

**Note on `review-completed` tag:** The business owner manually adds this tag when they see a new Google review posted, or it can be automated via Google Business Profile webhook if available. Tag the contact in GHL manually: Contacts > [Contact] > Tags > Add `review-completed`.

---

## Rating Landing Page — GHL Funnel Specification

**Funnel name:** `Reputation Rocket — Rating Page`
**Page URL slug:** `rate-[business-slug]` (e.g., `rate-smith-plumbing`)

### Page Elements (top to bottom)

1. **Header** — Business logo + "How did we do?" headline + "Your feedback means everything to us" sub-headline
2. **Technician callout** — "You were served by {{technician_name}} today." (light grey box)
3. **Star rating form** — 5 tappable stars, maps to `review_rating` custom field. Large submit button: "Submit My Rating"
4. **Footer** — "Your feedback is private and secure." in small grey text

### Post-Submit Redirects

| Rating | Redirect | Destination |
|---|---|---|
| 5 stars | Google Review link | `{{custom_field.google_review_link}}` |
| 4 stars | Google Review link | `{{custom_field.google_review_link}}` |
| 3 stars | Thank you page | `/thank-you-feedback` |
| 2 stars | Thank you page | `/thank-you-feedback` |
| 1 star | Thank you page | `/thank-you-feedback` |

**Implementation note:** Use GHL Survey element (not standard Form) for conditional per-answer redirects. Each star value = separate answer = separate next-step URL.

### Thank You Page (1-3 star ratings only)

Headline: "Thank you for your honesty."
Body: "We genuinely appreciate you taking the time to share your experience. A member of our team will be in touch shortly."
No Google Review link. No social sharing buttons. No further CTAs.

---

## GHL Custom Fields Required

Create all four fields before building workflows:

| Field Name | Display Label | Type | Used In |
|---|---|---|---|
| `google_review_link` | Google Review Link | Text | Workflow 2, SMS Template 1, Follow-up |
| `technician_name` | Technician Name | Text | SMS Template 1, Template 2, internal alert |
| `job_type` | Job Type | Text | Internal notification, contact note |
| `review_rating` | Review Rating | Numerical | Workflow 2 branch condition |

---

## GHL Pipeline: Reputation Tracker

**Pipeline name:** Reputation Tracker

| Stage | Name | Colour | Description |
|---|---|---|---|
| 1 | Review Requested | Green (#22C55E) | 4-5 star rating received, Google link sent |
| 2 | Negative Feedback | Red (#EF4444) | 1-3 stars received, owner notified, no Google link |
| 3 | Review Posted | Blue (#3B82F6) | Owner manually moves here when Google review confirmed |

---

## n8n Bridge for External Job Management Systems

### ServiceM8 / Tradify → GHL Trigger

When a job is marked "Complete" in ServiceM8 or Tradify, n8n bridges the event to GHL:

**n8n Workflow: ServiceM8 Job Completion Bridge**

```
TRIGGER: ServiceM8 webhook — job.status = "completed"
         |
         v
NODE 1: Extract job data
  - customer_phone
  - technician_name
  - job_type
  - business_name
  - google_review_link (from static config or mapping table)

         |
         v
NODE 2: HTTP Request — GHL Webhook
  - Method: POST
  - URL: [GHL sub-account webhook URL from RR-01 trigger]
  - Body:
    {
      "contact_phone": "{{customer_phone}}",
      "technician_name": "{{technician_name}}",
      "job_type": "{{job_type}}",
      "business_name": "{{business_name}}",
      "google_review_link": "{{google_review_link}}"
    }

         |
         v
NODE 3: Log result
  - On success: Log job_id + timestamp
  - On error: Alert via email/Slack
```

**n8n Workflow JSON:** Export the above as an n8n JSON file after building. Store alongside this file.

---

## Deployment Checklist

### Pre-Deployment (Agency Level)
- [ ] GHL agency account has SaaS Mode active
- [ ] Client sub-account provisioned
- [ ] SMS number assigned to sub-account
- [ ] Agency API key available

### Per-Client Configuration
- [ ] Client's Google Review link obtained (GBP Dashboard > Get more reviews)
- [ ] Client's business trading name confirmed
- [ ] Technician name(s) confirmed (or set to business name if solo)
- [ ] Owner's notification email address confirmed

### GHL Asset Creation
- [ ] 4 custom fields created (google_review_link, technician_name, job_type, review_rating)
- [ ] Reputation Tracker pipeline created (3 stages)
- [ ] SMS Template 1 (RR - Review Request) created
- [ ] SMS Template 2 (RR - Review Follow-Up) created
- [ ] Rating funnel built and published — URL noted
- [ ] Thank you page built and published
- [ ] Workflow 1 (RR-01) created, both triggers active, filters set
- [ ] Workflow 2 (RR-02) created, branch logic verified
- [ ] Workflow 3 (RR-03) created, 48h delay confirmed
- [ ] All workflows set to Active

### Post-Deployment Testing
- [ ] Create test contact with own mobile number
- [ ] Add tag `review-requested` — confirm SMS received within 2h 5min
- [ ] Tap link — confirm rating page loads and stars are tappable
- [ ] Submit 5 stars — confirm Google Review redirect fires
- [ ] Submit 1 star with second test contact — confirm internal alert email fires, no Google link sent
- [ ] Confirm pipeline stages updated correctly for each test
- [ ] Confirm follow-up SMS fires at 48h mark (or test with 1-min delay in staging)

---

*Workflow Spec: REVIEW_GENERATOR_WORKFLOW.md v1.0.0 | ReceptionistAI | Genesis Build*
*Module maintained by Sunaiva Digital — ops@sunaivadigital.com*
