openclaw/ad-engine

Ad Engine — Facebook Ads Deployment

Assemble ads from database components and deploy to Facebook. Reads from Supabase ad_components + messages tables, assembles full ad copy, uploads images, and creates Campaign → Ad Set → Ad in Facebook Ads Manager.

First-Time Setup

1. Facebook prerequisites (one-time, manual):

• Facebook Business Manager account
• Ad Account created
• Facebook Page connected
• Facebook Developer App with ads_management permission
• Long-lived access token (generate at developers.facebook.com)

2. Store credentials:

python3 scripts/fb_deploy.py --setup

Prompts for access token, ad account ID, and page ID. Validates against FB API and saves to ~/.config/ad-engine/fb_config.json.

Usage

Preview assembled ads (no deployment):

# Preview a single ad
python3 scripts/fb_deploy.py --preview --message-id 8555

# Preview all draft ads for a campaign
python3 scripts/fb_deploy.py --preview --campaign-id 43

# Preview as JSON
python3 scripts/fb_deploy.py --preview --campaign-id 43 --json

Deploy a single ad:

python3 scripts/fb_deploy.py --deploy \
  --message-id 8556 \
  --image /path/to/security-audit-ad.png \
  --landing-url "https://calendly.com/your-link" \
  --objective messages

Deploy all draft ads for a campaign:

python3 scripts/fb_deploy.py --deploy \
  --campaign-id 43 \
  --image-dir /path/to/ad-images/ \
  --landing-url "https://calendly.com/your-link" \
  --objective messages

Dry run (preview what would be created):

python3 scripts/fb_deploy.py --deploy \
  --campaign-id 43 \
  --image-dir /path/to/images/ \
  --landing-url "https://calendly.com/link" \
  --dry-run

Check deployed ad status + live metrics:

python3 scripts/fb_deploy.py --status --campaign-id 43

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --preview | One of | Preview assembled ads without deploying | | --deploy | these | Deploy ads to Facebook | | --status | three | Check status of deployed ads | | --setup | | Configure Facebook credentials | | --message-id | For single | Specific message ID to preview/deploy | | --campaign-id | For batch | All draft ads in a campaign | | --image | Deploy single | Image file path | | --image-dir | Deploy batch | Directory of images (matched by angle name in filename) | | --landing-url | Deploy | Booking/landing page URL | | --objective | No | leads (default), messages, or link_clicks | | --dry-run | No | Preview deployment without creating anything | | --json | No | Output as JSON |

Image Naming Convention

When using --image-dir for batch deploy, name images by angle:

security-audit-ad.png      → matches angle "security_audit"
setup-is-hell-ad.png       → matches angle "setup_is_hell"
dm-trigger-checklist.png   → matches angle "dm_trigger"
anti-wrapper-graveyard.png → matches angle "anti_wrapper"

How It Works

1. Reads message from Supabase messages table (content_type = 'fb_ad')
2. Reads component references from message's extra_data.components
3. Resolves component keys → actual text from ad_components table
4. Slots components into framework template using {{merge_tags}}
5. Uploads image to Facebook → gets image_hash
6. Creates Campaign (if new) → Ad Set (if new) → Ad Creative → Ad
7. Updates message status to 'deployed' with FB IDs stored in extra_data

Database Schema

See AD_ENGINE_SPEC.md for full schema documentation.

Dependencies

• psycopg2-binary — Supabase Postgres connection
• facebook-business — Facebook Marketing API SDK
• requests — HTTP client
• All auto-installed on first run.