Lead Tags
Audience: Support · QA · Engineering · Where in app: Leads (Tags column, drawer, bulk Add/Remove tag, Tags filter, CSV), Settings → Tags (/settings/tags), automation Add tag step, campaign Tag step and call-result actions · Plan availability: all accounts · Shipped: backend 847865285 + frontend aade9d30 (2026-11-04); system tags backend 74bfe7fe0 + frontend 7f3ff19a (2026-11-09)
Data model
| Collection | Model | Shape |
|---|---|---|
tags | TagModel | {company_id, name, slug, color} — slug = lower-cased, whitespace-collapsed name (≤60 chars), unique per company, so "VIP" = "vip". Colours: teal blue violet amber rose green orange slate |
contact_tags | ContactTagModel | {company_id, keys[], tag_ids[]} — one doc per person, keyed by contact keys, indexes {company_id, keys} and {company_id, tag_ids} |
Tags sit on people, not on a Leads row, campaign lead or automation contact. A person is their contact keys (lib/contactKeys): e:<lower-cased email> and p:<last 10 phone digits> (a lead with neither is keyed l:<lead row key>). The same person therefore carries the same tags on the Leads page, in campaigns and in automations. Leads rows store contact_keys (indexed) to join and filter; the API strips them from responses. TagService.apply folds two docs that turn out to be the same person (an email on one, a phone on the other) into one; an edited lead email/phone calls relink, which adds the new keys to the existing docs.
API (tagRoutes.js → TagController → TagService)
All under passport + companyPaused, canManageCompany:
GET /tags/:company_id— every tag withcount(people carrying it) andused_by(automations and campaigns whose steps/triggers name it).GET /tags/:company_id/crm— connected CRMs{provider, label, tags}and the CRM's own tag names, for the picker's suggestions (GHLlistLocationTags; HubSpot reportstags: truevia thekk_tagsmulti-select; other CRMstags: false).POST /tags/:company_id{name, color}(create / ensure),PUT /tags/:company_id/:id(rename/recolour),POST /tags/:company_id/:id/merge{into},DELETE /tags/:company_id/:id(pulls the id off everycontact_tagsdoc).POST /leads/:company_id/tags{ids, add, remove}— bulk tag Leads rows (≤1000 rows, ≤20 names; unknown names inaddare created). Returns each row's tags.
Rename and merge rewrite the names inside automation_rules (graph.nodes[].options.tags, triggers[].tag / legacy trigger.tag) and campaigns (steps[].options.tags|tag, call outcomes.*.tags|tag) via TagService.walkRefs, then drop the rule cache (AgentKRuleService.forgetRules). Delete does not rewrite refs — a step that adds the tag recreates it on its next run (the confirm dialog says so).
Tag steps
Automation tag action and campaign tag step/outcome action options: { tags: [..], mode: 'add'|'remove', where: { lead, crm } } (≤ the graph's tag limit). A step saved before lead tags (no where) stays CRM-only; a campaign's old single tag / per-result tag(s) read as a list (the editor upgrades older call results to a first tag action with the same node id — 40bb7fccc).
where.lead→TagService.applyon the run's person.where.crm→ the CRM contact, only wherecrm/capabilitieshastags: true(GHL tags; HubSpotkk_tags). Skipped while the person has no CRM contact; mailbox stand-in ids (mbx_) count as no CRM. GHL tag writes go throughaddTags/ named removes only —23744b9f5(2026-10-23) stopped upserts and updates sendingtagsin the body, which made GHL replace the contact's whole tag list (an inbound-call upsert wiped a tenant's tags);GhlAdapter.setTagswas removed. Besides a remove step, the funnel stage swap is the only path that removes tags.
tag_added trigger
TagService.apply fires AgentKRuleService.onEvent({ types: ['tag_added'], tags }) for each person who newly gets a tag (Leads page, another automation or campaign). The GHL side fires the same trigger from ContactTagUpdate webhooks (GhlNativeEventHelper), diffing against Redis so only newly seen tags count (a tag present the first time we see the contact counts too). The editor's trigger picks its tag from the same picker (FormTagInput, single).
System tags (read-only)
lib/systemTags.js derives the tags Knock Knock itself writes to the CRM from our own records — Agent K (nextlevel agent-k-lead, nextlevel signal:<signal>, nextlevel source:<source>, nextlevel list:<import tag>, nextlevel phone-found) and the funnel stage tag (<nox_funnel.stage_tag_prefix><stage>, the default nextlevel stage: when the tenant turned mirroring off) — so every account sees them, CRM or not. Stored on leads.system_tags (indexed), filtered with system_tag=, listed in the index response's system_tags, exported as Automatic tags. test/system-tags.spec.js pins the formats to AgentKPushService / FunnelStageService. The drawer also gets crm_tags — a GHL contact's live tags (4 s bound) — shown as "Also in your CRM" minus the system ones.
Frontend
components/tags/ — TagPicker.vue (teleported to <body> so tables don't clip it; search, keyboard, create, CRM suggestions), TagChip.vue, TagInput.vue, TagActionFields.vue (Add/Remove + Where cards), tagColors.js; composables/useTags.js; repositories/tags.js; components/form/FormTagInput.vue. Settings page views/settings/tags/Index.vue + TagDialog.vue (create / edit / merge), menu entry in useSettingsMenu gated leads.view + pages.leads. Smoke: node scripts/smoke-tags.js (local mongo).
Related
- Leads — Overview · Automations · Campaigns
- Nox Funnel — stage-tag mirroring