Skip to main content

Campaigns (beta)

Audience: Support · QA · Engineering · Where in app: Build → Automations → Campaigns tab (/campaigns, /campaigns/new, /campaigns/:id, /campaigns/:id/edit), Leads → Add to campaign · Plan availability: beta — super-admin switch companies.campaigns_enabled · Shipped: backend 9f6264a35 (2026-11-03), 3d5ec0e86, 847865285 (tag lists), 9827ea81a (Leads enrol + Triggered by), 76b4d9154 (customers), 40bb7fccc (call-result actions, webhook presets, Leads filters); frontend 4e98de78, f3f2cc16 (moved from the sidebar into the Automations tab bar), aade9d30, 6e0295af, 855a7c67

A campaign walks a lead list through ordered steps. The steps compile to an agentKGraph workflow, and each lead is an ordinary automation run (AgentKAutomationService.runGraph) on an automation contact with origin { source: 'campaign', campaign_id } — so waits, call checks, stop rules, quiet hours, DND/suppression, the frequency cap and the automation log (automation_events) all come from the automation engine. CampaignService only adds the list, the daily pacing and the calling window.

Gating​

  • companies.campaigns_enabled (default false), toggled by super-admin PUT /company/:_id/campaigns (admin Companies → Detail "Campaigns (beta)"). The frontend shows the Campaigns tab (AutomationTabs.vue) and the Leads Add to campaign button only with it on; the page itself says "Campaigns is in beta" when off.
  • Switching it off holds running campaigns like a pause: tick skips them, statusOf reports paused, and ScheduledNoxActionJob defers their queued calls/texts (defer_reason: 'campaign_paused'). Routes are settings.ai + settings.ai_agents (same as Automations).

Data model​

CollectionModelNotes
campaignsCampaignModelname, goal (book_appointments | reengage | missed_call | blank), attribution_category ('' = from goal), status (draft | running | paused | completed), agent_key, sms_agent_key, steps[] (editor shape), graph (compiled), schedule {days, start_hour, end_hour, per_day, start_at}, counters {day, started} (company-day), import {state, source, label, added, skipped, error, at}
campaign_leadsCampaignLeadModelunique {campaign_id, key}; name/phone/email/company_name, crm_provider + crm_id (run acts on that CRM contact), status queued | active | done | skipped + reason, contact_id (automation contact), event_id
ghl_workflow_triggersGhlWorkflowTriggerModelone per GHL workflow using our trigger: trigger_id (unique), company_id, location_id, key, target_url, workflow_id, filters, last_fired_at, last_error

Limits: MAX_LEADS 20 000 per campaign, MAX_ROWS 5000 per add, schedule per_day 1–1000 (default 50), default window Mon–Fri 09–18.

Steps (lib/campaignSteps.js)​

call { agent_key, context, retries 0-3, retry_hours,
outcomes: { booked|answered|unanswered: { then: 'end'|'continue', actions: [{ type, options }] } } }
sms { agent_key, mode: plain|ai, message, context }
email { mode: template|ai, subject, body, instruction }
wait { days, hours }
tag { tags[], mode: add|remove, where: { lead, crm } } (old single `tag` still read)
notify { message }
webhook { url, service: ''|zapier|make|n8n|custom }

compile turns a call into 1 + retries ai_call nodes chained by if call_answered / if call_booked checks (the call_booked check is new in the shared engine) and wait retry_hours nodes; each result's actions (≤5 of sms, email, tag, notify, webhook — OUTCOME_ACTIONS) run in order before then goes on or ends. "Unanswered" means after the last try. A call whose every result ends while later steps exist is refused. Older campaigns that tagged per result open with that tag as the result's first tag action, same node id (40bb7fccc). The frontend mirror is views/campaigns/campaign.js (STEP_TYPES, GOALS, OUTCOMES, reachPerLead for the launch page's "up to N calls…").

Webhook action (AgentKActionRunner._webhook, shared with automations): ssrfBlockReason refuses private/local targets up front (IP literals skip DNS; the SSRF-safe agents cover rebinding), 10 s timeout. Body: { event: 'campaign.step'|'automation.step', trigger?: 'call.booked'|'call.answered'|'call.unanswered', campaign_id, rule_id, step, at, contact: {name, email, phone, company, crm_contact_id} }. The service presets are UI-only (hints for where to find the URL).

Running (CampaignJob → CampaignService.tick, schedular, every minute)​

  1. Start due leads of each running campaign whose start_at has passed and whose window is open in the company's timezone: up to START_PER_TICK (5) a minute and per_day minus today's counters.started. Each lead is checked against suppression (NoxGhlActionService.isSuppressed), gets an automation contact keyed lead:<key> (and a CRM contact when one is connected), then its run starts. A failing start → skipped/start_failed.
  2. Sweep active leads whose run ended → done.
  3. Complete a campaign with no queued/active leads left.
  4. Fire kk_campaign_call_ended for settled campaign calls to every subscribed GHL target.

Calls and texts queue as ScheduledNoxActions; ScheduledNoxActionJob holds them outside the campaign's hours in the lead's timezone (from the phone number via PhoneTimezoneHelper) and while the campaign is paused. Deleting a campaign cancels what it queued. Leads already under way keep the graph they started with; edits apply to new starts.

Customers — with nox_funnel.customers.mode = 'stop_selling' (default), adding leads skips funnel customers (Won / flags.customer, matched by email, phone or CRM id) as customer (76b4d9154). Touches are stamped touchAttribution.forRun({source:'campaign'}) → <category> · Campaign: <name> (category: attribution_category, else missed_call → intent_trigger, else reactivation).

Adding leads​

POST /campaigns/:id/leads (rows from CSV/paste — the editor maps columns client-side), POST /campaigns/:id/leads/crm (everyone with a GHL tag — background import, CRM_PAGE 100 × CRM_MAX_PAGES 50, progress in campaign.import, stale after 15 min; tag list from GET /campaigns/crm-tags, GHL only), POST /campaigns/:id/leads/site (Leads page rows by SITE_TABS all|hot|not_contacted|chat|call|form, funnel stage incl. none, last_touch never|7|30|90, active-in days — reuses leadRows.tabFilter/leadFilter), and POST /leads/:company_id/campaign from the Leads page (see Leads overview). Skip reasons: no_contact, no_phone, phone_needs_country, no_email (by what the steps need), duplicate, already_added, campaign_full, too_many, customer, booked_or_won (Leads enrol).

Endpoints (campaignRoutes.js, passport + companyPaused)​

GET/POST /campaigns, GET /campaigns/crm-tags, GET/PUT/DELETE /campaigns/:id, POST /campaigns/:id/{launch,pause,resume}, GET/POST /campaigns/:id/leads, POST /campaigns/:id/leads/{crm,site}, DELETE /campaigns/:id/leads/:leadId.

LeadConnector​

Public routes (same auth as the other GHL custom actions — unsigned unless GHL_ACTION_REQUIRE_SIGNATURE=true):

  • POST /go-high-level/action/campaigns — the Add to campaign action's dropdown (this location's campaigns, with (draft)/(paused)/(finished) notes).
  • POST /go-high-level/action/add-to-campaign — the workflow's contact joins the campaign.
  • POST /go-high-level/workflow-trigger/subscribe — GHL's subscription calls for the Campaign call ended trigger. Key is kk_campaign_call_ended (GHL reserves campaign_call_ended app-wide, 3d5ec0e86); targetUrl must be on services.leadconnectorhq.com; the location must belong to a company with campaigns_enabled. Results sent: booked, talked, voicemail, no_answer — tenants filter on campaign + result.

Go-live: register the trigger (key kk_campaign_call_ended) and the two actions in the GHL marketplace app.

Frontend​

views/campaigns/ — Campaigns.vue (goal cards always on top, then "Your campaigns" with KPIs), CampaignEditor.vue (Goal → Steps → Schedule → Leads → Launch), StepCard.vue, AddStepMenu.vue, CallResults.vue + ActionDialog.vue (per-result action chains), LeadsImport.vue (Upload a CSV / Paste or type / From your CRM / From your Leads), CampaignDetail.vue (KPIs, progress bar, per-lead status, pause/resume/add/edit/delete, the GHL hint); repositories/campaigns.js. Routes keep Automations highlighted in the sidebar.

Smoke: node scripts/smoke-campaign.js (local mongo). Specs: campaign-steps, leads-controller-campaign.