campaign-orchestrator

# Campaign Orchestrator Skill

Multi-channel follow-up campaign orchestrator for ShapeScale sales. Executes scheduled SMS + Email sequences with CRM integration and auto-termination on replies.

## Overview

A **Campaign** is a defined sequence of steps (SMS/Email) that executes over time. When a lead replies to any message, the campaign automatically terminates.

### Key Features

- **Multi-channel**: SMS (Dialpad) + Email (Gmail)
- **Scheduled**: Cron-based execution with configurable delays
- **Personalized**: Templates filled from Attio CRM data
- **Auto-terminating**: Replies stop all future scheduled steps
- **Logged**: All activities recorded in Attio

## Setup

**Environment variables required:**
```bash
DIALPAD_API_KEY=your_dialpad_api_key
ATTIO_API_KEY=your_attio_api_key
GOG_KEYRING_PASSWORD=your_google_password  # For Gmail access
```

**Also ensure:**
- Dialpad webhook is configured to hit this server
- Attio has company/contact records for leads
- Gmail API access enabled for sales email

## Usage

### Start a Campaign

```bash
# Start primary follow-up campaign for a lead
python3 campaign.py start "primary" --lead "Apex Fitness"

# Start with custom delay override (hours)
python3 campaign.py start "primary" --lead "Apex Fitness" --delay 2

# Start with Attio deal/company ID
python3 campaign.py start "post-demo" --lead "Apex Fitness" --attio-id "deal-uuid"
```

### Pre-Campaign Checklist (MANDATORY)

Before starting ANY campaign, verify:

1. **Customer Status Check**
   - Search memory/CRM for "already a customer" or "purchased" flags
   - Check exclusion list in campaigns.json
   - Verify email domain not in customer database

2. **Email Formatting Check** (for email steps)
   - Preview template renders as proper paragraphs
   - 2-4 sentences per paragraph, blank line between
   - No single-sentence orphan paragraphs
   - No hard line breaks mid-paragraph

3. **Tone Check**
   - No apologetic language ("no worries", "sorry to bother")
   - No easy outs ("if not relevant, no problem")
   - Professional, not needy

**NEVER campaign to existing customers unless explicitly requested for upsell.**

### Check Campaign Status

```bash
# Status for specific lead
python3 campaign.py status "Apex Fitness"

# All active campaigns
python3 campaign.py list
```

### Stop a Campaign

```bash
# Manual termination (lead replied, not interested, etc.)
python3 campaign.py stop "Apex Fitness" --reason "replied_interested"
```

### Remove a Lead

```bash
# Remove lead from campaigns (opted out, not interested)
python3 campaign.py remove "Apex Fitness"
```

### Check for Responses

```bash
# Check if lead has responded to any prior messages
python3 campaign.py check "Apex Fitness"
# Shows response status for each completed step
# Warns if responses detected (safe to proceed or terminate)
```

### View Pending Steps

```bash
# Show all pending campaign steps sorted by time
python3 campaign.py pending
# Useful for seeing what's due soon across all campaigns
```

### Template Management

```bash
# List available templates
python3 campaign.py templates

# Preview a template
python3 campaign.py preview "primary"
```

## Campaign Templates

| Template | Timing | Channel | Purpose |
|----------|--------|---------|---------|
| `primary` | +4 hours | SMS | Recap demo, share recording |
| `secondary` | +1 day | Email | Pricing, detailed ROI |
| `tertiary` | +4 days | SMS | Quick check-in |
| `quaternary` | +7 days | Email | Final follow-up, case study |
| `post-demo` | +0 hours | SMS | Immediate thank you |

### Template Variables

Templates support variable substitution:

```
{name}      - Lead first name
{company}   - Company name
{deal_value} - Deal value from Attio
{owner}     - Sales owner name
{demo_notes} - Notes from demo conversation
{checkout_link} - Personalized checkout URL
```

## Architecture

```
campaign-orchestrator/
├── SKILL.md              # This file
├── campaign.py           # Main CLI (start, stop, status, list)
├── webhook_handler.py    # Processes reply → termination
├── primary.md            # SMS follow-up template
├── secondary.md          # Email template
├── post-demo.md          # Immediate follow-up template
└── state/
    └── campaigns.json    # Campaign state persistence
```

## State Management

Campaign state is stored in `<workspace>/state/campaigns.json`:

```json
{
  "campaigns": {
    "Apex Fitness": {
      "template": "primary",
      "attio_id": "deal-uuid",
      "started": "2026-01-27T13:00:00Z",
      "steps_completed": ["sms_primary"],
      "next_step": "email_secondary",
      "next_scheduled": "2026-01-28T13:00:00Z",
      "status": "active"
    }
  },
  "templates": {
    "primary": {...},
    "secondary": {...}
  }
}
```

## Cron Integration

Campaign steps are executed via Clawdbot's cron system:

- **Executor job**: Runs every 5 minutes to check for due steps
- **Per-campaign jobs**: Created for each scheduled step

The scheduler script creates and manages these jobs automatically.

## Webhook Handling

When Dialpad receives a reply to a campaign message:

1. Dialpad sends webhook to server
2. `webhook_handler.py` parses the reply
3. Looks up which campaign the original message belonged to
4. Marks campaign as terminated
5. Logs the reply to Attio

## Integration Points

### Dialpad SMS
```bash
python3 /home/art/niemand/skills/dialpad/send_sms.py --to "+14155551234" --message "..."
```

### Gmail (via gog)
```bash
gog-shapescale --account martin@shapescale.com send-email --to "lead@company.com" --subject "..." --body "..."
```

### Attio CRM
```bash
attio note companies "company-uuid" "Campaign message sent: {message}"
```

## Examples

### Full Campaign Workflow

```bash
# 1. After demo, start campaign
/campaign start "post-demo" --lead "Dr. Smith's Clinic"

# 2. Check status next day
/campaign status "Dr. Smith's Clinic"
# Output: Step 1 sent, Step 2 scheduled for tomorrow

# 3. Lead replies "interested"
# Webhook automatically terminates campaign
# Logs reply to Attio

# 4. Manual follow-up if needed
/campaign start "secondary" --lead "Dr. Smith's Clinic" --delay 0
```

### Monitoring Active Campaigns

```bash
# List all active
/campaign list

# Output:
# Active Campaigns:
# - Apex Fitness (primary) - Step 2/4, next: email
# - Dr. Smith's Clinic (post-demo) - Complete
# - Wellness Center (tertiary) - Step 1/3, next: sms
```

## Troubleshooting

**Campaign not sending:**
- Check `cron` is running: `crontab -l`
- Check logs: `journalctl -u moltbot` or campaign logs
- Verify API keys: `echo $DIALPAD_API_KEY`

**Webhook not terminating:**
- Verify Dialpad webhook URL is configured
- Check webhook handler is running
- Check `campaigns.json` for matching lead

**Template variables not filling:**
- Verify lead exists in Attio with required fields
- Check template syntax: `{variable}` not `{ variable }`

## License

Part of shapescale-moltbot-skills. See parent repository.