gb/prompts/campaigns.md

Campaigns - Multichannel Marketing Platform

Overview

Unified campaign management system supporting email, WhatsApp, Instagram, and Facebook with AI-powered content generation and targeting.

Core Tables

1. marketing_campaigns

Main campaign entity linking deals, contacts, and metrics.

Column	Type	Description
id	uuid	Primary key
org_id	uuid	Organization
bot_id	uuid	Bot
name	varchar(100)	Campaign name
status	varchar(20)	draft, scheduled, running, paused, completed
channel	varchar(20)	email, whatsapp, instagram, facebook, multi
content_template	jsonb	AI-generated content per channel
scheduled_at	timestamptz	When to send
sent_at	timestamptz	When actually sent
metrics	jsonb	Opens, clicks, responses
budget	numeric	Campaign budget
created_at	timestamptz
updated_at	timestamptz

2. marketing_lists

Saved recipient lists (static or dynamic).

Column	Type	Description
id	uuid	Primary key
org_id	uuid	Organization
bot_id	uuid	Bot
name	varchar(100)	List name
list_type	varchar(20)	static, dynamic
query_text	text	SQL-like filter or broadcast.bas path
contact_count	int	Cached count
created_at	timestamptz
updated_at	timestamptz

3. marketing_list_contacts

Junction table for static lists.

Column	Type	Description
list_id	uuid	FK to marketing_lists
contact_id	uuid	FK to crm_contacts
added_at	timestamptz

4. marketing_recipients

Track campaign delivery per contact.

Column	Type	Description
id	uuid	Primary key
campaign_id	uuid	FK to marketing_campaigns
contact_id	uuid	FK to crm_contacts
deal_id	uuid	FK to crm_deals (nullable)
channel	varchar(20)	email, whatsapp, etc
status	varchar(20)	pending, sent, delivered, failed
sent_at	timestamptz
delivered_at	timestamptz
opened_at	timestamptz	Email open (pixel)
clicked_at	timestamptz	Link click
response	jsonb	WhatsApp status callback

5. marketing_templates

Content templates with AI prompts.

Column	Type	Description
id	uuid	Primary key
org_id	uuid	Organization
name	varchar(100)	Template name
channel	varchar(20)	email, whatsapp, instagram, facebook
subject	varchar(200)	Email subject / WhatsApp text
media_url	varchar(500)	Image/video URL
ai_prompt	text	Instructions for LLM
variables	jsonb	Available placeholders
approved	boolean	Meta approval status
meta_template_id	varchar(100)	Meta template ID
created_at	timestamptz

6. email_tracking

Email-specific metrics (invisible pixel + link tracking).

Column	Type	Description
id	uuid	Primary key
recipient_id	uuid	FK to marketing_recipients
campaign_id	uuid	FK to marketing_campaigns
message_id	varchar(100)	SMTP message ID
open_token	uuid	Unique pixel token
opened	boolean
opened_at	timestamptz
clicked	boolean
clicked_at	timestamptz
ip_address	varchar(45)
user_agent	varchar(500)

7. whatsapp_business

WhatsApp Business API configuration.

Column	Type	Description
id	uuid	Primary key
bot_id	uuid	Bot
phone_number_id	varchar(50)	Meta phone ID
business_account_id	varchar(50)	Meta business ID
access_token	varchar(500)	Encrypted
webhooks_verified	boolean

Flow

1. Campaign Creation

1. User clicks "New Campaign"
2. Selects channel(s): email, whatsapp, instagram, facebook, multi
3. Chooses audience:
   • broadcast.bas: If present in .gbdialog, execute and use returned contact list
   • Marketing List: Select from saved lists
   • Dynamic Query: Build SQL-like filter
4. AI generates content preview for each channel
5. User edits/approves content
6. Schedule or send immediately

2. Audience Selection

// broadcast.bas example (.gbdialog/scr/broadcast.bas)
SEND "SELECT id, name, phone, email FROM crm_contacts WHERE tags @> '{prospect}'"

// Result: list of contact UUIDs

3. Content Generation

• LLM receives: contact data, deal info, campaign goal
• Generates: subject, body text, image suggestion
• User can edit before approval

4. Multi-Channel Preview

Single UI showing:

• Email preview (desktop/mobile)
• WhatsApp preview (text + image)
• Instagram/Facebook post preview
• "Publish All" button triggers all channels

5. Metrics Sync

• Email: Invisible 1x1 pixel for opens, tracked links for clicks
• WhatsApp: Webhook callbacks from Meta API
• Instagram/Facebook: Graph API for insights

Deal Integration

• Pipeline stage changes can trigger campaigns
• Deals link to campaigns via marketing_recipients.deal_id
• Campaign metrics visible in deal sidebar

File Structure

botserver/src/
  marketing/
    mod.rs           # Routes, handlers
    campaigns.rs     # CRUD operations
    lists.rs         # List management  
    templates.rs     # Template management
    email.rs         # Email sending + tracking
    whatsapp.rs      # WhatsApp API integration
    metrics.rs       # Metrics aggregation
    ai.rs            # Content generation

Dependencies

• WhatsApp: meta-whatsapp-business-webhook
• Email: lettre (SMTP) + tracking pixel
• Instagram/Facebook: facebook-graph-api
• AI: Already have LLM integration in designer