Logo
Docs

Tags and Custom Fields

Add metadata to visitors with tags and custom fields for better categorization and context.

Tags and custom fields allow you to store additional metadata about your visitors. Use tags for quick categorization and custom fields for any key-value data you need.

Quick Overview

Tags are simple labels for categorizing visitors:

  • Examples: vip, paid-user, trial, onboarding-complete
  • Perfect for quick filtering and segmentation
  • Display as badges in the dashboard

Custom Fields are flexible key-value pairs for any metadata:

  • Examples: plan: "premium", signup-date: "2025-01-15", is-subscribed: true
  • Support strings, numbers, and booleans
  • Display with smart formatting (dates, URLs, emails, etc.)

Tags

Adding Tags

Add tags to categorize visitors:

// Add single tag
HEYO.addTag('vip');
HEYO.addTag('paid-user');
HEYO.addTag('onboarding-complete');

// Tags are stored as: 'vip', 'paid-user', 'onboarding-complete'
Tags are automatically normalized to kebab-case. "VIP Customer" becomes "vip-customer".

Removing Tags

Remove specific tags:

HEYO.removeTag('trial-user');

Setting All Tags

Replace all existing tags at once:

// Replace all tags with new set
HEYO.setTags(['premium', 'active', 'verified']);

Tag Examples

After successful payment:

// When payment completes
stripe.onPaymentSuccess(() => {
    HEYO.addTag('paid-user');
    HEYO.removeTag('trial-user');
});

Tracking onboarding progress:

// Step 1 complete
HEYO.addTag('onboarding-step-1');

// Step 2 complete
HEYO.addTag('onboarding-step-2');

// All done
HEYO.addTag('onboarding-complete');

User segments:

// Categorize users
if (user.isVIP) HEYO.addTag('vip');
if (user.region === 'EU') HEYO.addTag('eu-customer');
if (user.accountAge > 365) HEYO.addTag('long-term-user');

Custom Fields

Setting Fields

Add custom key-value data to visitors:

HEYO.setField('plan', 'premium');
HEYO.setField('signup-date', '2025-01-15');
HEYO.setField('is-subscribed', true);
HEYO.setField('monthly-revenue', 299);
Field keys are normalized to kebab-case: "Subscription Plan" becomes "subscription-plan".

Removing Fields

Remove specific custom fields:

HEYO.removeField('temp-data');

Supported Value Types

Custom fields support three value types:

Strings:

HEYO.setField('plan', 'premium');
HEYO.setField('subscription-id', 'sub_1A2B3C');

Numbers:

HEYO.setField('account-balance', 1500);
HEYO.setField('total-purchases', 42);

Booleans:

HEYO.setField('is-verified', true);
HEYO.setField('newsletter-subscribed', false);

Smart Value Display

Custom field values are automatically formatted based on their type in the dashboard:

URLs

HEYO.setField('website', 'https://example.com');
// Displays: Clickable link with external icon

Emails

HEYO.setField('support-email', '[email protected]');
// Displays: Clickable mailto link with email icon

Dates

HEYO.setField('trial-ends', '2025-02-15');
HEYO.setField('signup-date', '2025-01-15T10:30:00Z');
// Displays: "Feb 15, 2025" with calendar icon

Booleans

HEYO.setField('is-premium', true);
// Displays: Green checkmark + "Yes"

HEYO.setField('trial-expired', false);
// Displays: Gray X + "No"

Large Numbers

HEYO.setField('total-revenue', 125000);
// Displays: "125,000" (with commas)

Real-World Examples

E-Commerce Store

Track customer value and status:

// After user logs in
HEYO.identify({
    userId: user.id,
    email: user.email,
    name: user.name,
});

// Add relevant tags
HEYO.addTag('customer');
if (user.orders.length > 0) HEYO.addTag('has-purchased');
if (user.totalSpent > 1000) HEYO.addTag('high-value');

// Set custom fields
HEYO.setField('total-spent', user.totalSpent);
HEYO.setField('order-count', user.orders.length);
HEYO.setField('last-purchase', user.lastOrderDate);
HEYO.setField('is-vip', user.isVIP);

SaaS Application

Track subscription and usage:

// User subscription info
HEYO.setField('plan', user.subscription.plan); // "starter", "pro", "enterprise"
HEYO.setField('mrr', user.subscription.mrr);
HEYO.setField('trial-ends', user.subscription.trialEndsAt);
HEYO.setField('is-paying', user.subscription.isActive);

// Tags for quick filtering
HEYO.addTag(user.subscription.plan); // "starter", "pro", etc.
if (user.subscription.isActive) HEYO.addTag('paying-customer');
if (user.subscription.isTrial) HEYO.addTag('trial-user');

Onboarding Flow

Track user progress:

// Onboarding state
HEYO.setField('onboarding-step', 'profile-setup');
HEYO.setField('onboarding-started', '2025-01-15');
HEYO.setField('completed-steps', 3);

// Tags for each milestone
HEYO.addTag('onboarding-in-progress');

// When user completes onboarding
HEYO.removeTag('onboarding-in-progress');
HEYO.addTag('onboarding-complete');
HEYO.setField('onboarding-step', 'complete');
HEYO.setField('onboarding-completed', '2025-01-20');

Lead Scoring

Qualify leads automatically:

// Track engagement
HEYO.setField('page-views', sessionStorage.pageViewCount);
HEYO.setField('time-on-site', calculateTimeOnSite());
HEYO.setField('last-visit', new Date().toISOString());

// Qualify leads
if (user.downloadedWhitepaper) HEYO.addTag('qualified-lead');
if (user.requestedDemo) HEYO.addTag('hot-lead');
if (user.company.size > 50) HEYO.addTag('enterprise-prospect');

Server-Side API

You can also update tags and fields from your backend using our REST API:

Update Tags

// After payment webhook
await fetch(`/api/conversations/${conversationId}/tags`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({
        operation: 'add',
        tags: ['paid-user', 'premium'],
    }),
});

Update Custom Fields

// After subscription change
await fetch(`/api/conversations/${conversationId}/fields`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({
        operation: 'set',
        key: 'subscription-id',
        value: 'sub_1A2B3C4D',
    }),
});
operation
string required
For tags: add, remove, or set. For fields: set or remove.
tags
string | string[]
Single tag or array of tags (for tag operations).
key
string
Field key (for field operations).
value
string | number | boolean
Field value (for field set operation).

Limits and Validation

To ensure performance and data quality:

Tags:

  • Maximum 50 tags per visitor
  • Maximum 100 characters per tag
  • Automatically normalized to kebab-case

Custom Fields:

  • Maximum 50 fields per visitor
  • Maximum 500 characters for string values
  • Keys must be alphanumeric with dashes/underscores/dots
  • Automatically normalized to kebab-case
Key Normalization: Field keys and tags are automatically converted to kebab-case for consistency. "User Plan" becomes "user-plan", but displays as "User Plan" in the dashboard.

Best Practices

Choose Tags for Categories

Use tags when you need simple categorization:

// ✅ Good - simple categories
HEYO.addTag('premium');
HEYO.addTag('active');
HEYO.addTag('verified');

// ❌ Avoid - complex state better in fields
HEYO.addTag('plan-premium-monthly-299'); // Use custom field instead

Choose Custom Fields for Data

Use custom fields for specific values:

// ✅ Good - structured data
HEYO.setField('plan', 'premium');
HEYO.setField('billing-cycle', 'monthly');
HEYO.setField('price', 299);

// ❌ Avoid - boolean states better as tags
HEYO.setField('is-premium', true); // Use tag instead

Naming Conventions

Use clear, descriptive names:

// ✅ Good
HEYO.addTag('trial-user');
HEYO.setField('subscription-plan', 'pro');

// ❌ Avoid abbreviations
HEYO.addTag('trl');
HEYO.setField('sub-pln', 'pro');

Keep It Simple

Don't over-tag or over-field:

// ✅ Good - essential info
HEYO.addTag('paying-customer');
HEYO.setField('plan', 'pro');
HEYO.setField('mrr', 99);

// ❌ Too much - overwhelming
HEYO.addTag('customer');
HEYO.addTag('paying');
HEYO.addTag('active');
HEYO.addTag('verified');
HEYO.addTag('engaged');
// ... 20 more tags

Dashboard View

Your support team will see:

Tags appear as colored badges at the top of visitor details, making it easy to quickly identify visitor segments.

Custom Fields appear as a structured list with smart formatting:

  • URLs become clickable links
  • Emails become mailto links
  • Dates show formatted (e.g., "Jan 15, 2025")
  • Booleans show as checkmarks (✓ Yes / × No)
  • Numbers format with commas (1,234,567)

Your team can also add, edit, or remove tags and fields directly from the dashboard.

Next Steps: Learn about Widget Events to respond to widget state changes, or explore Agent Status to check agent availability.

Widget Events

Listen to widget events and execute code at the right time.

Platform list

Installation and integration guides tailored for your favorite platforms and frameworks.