Visitors & Users

Transactional Support tracks visitors on your site and allows you to identify them as users.

Visitor vs User

Type	Description
Visitor	Anonymous person browsing your site
User	Identified person (logged in or identified via SDK)

When a visitor is identified, all their previous conversations and data are merged into their user profile.

Identifying Visitors

Basic Identification

TransactionalSupport('identify', 'user-123', {
  name: 'John Doe',
  email: 'john@example.com'
});

With Custom Attributes

TransactionalSupport('identify', 'user-123', {
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890',
  createdAt: '2024-01-01',
 
  // Custom attributes
  plan: 'premium',
  company: 'Acme Inc',
  role: 'Admin',
  monthlySpend: 500,
  lastLoginAt: new Date().toISOString()
});

Updating Attributes

// Update existing user attributes
TransactionalSupport('update', {
  plan: 'enterprise',
  monthlySpend: 2000
});

Visitor Profile

View in Dashboard

Navigate to Support > Visitors
Search for a visitor by name or email
Click to view their profile

Profile Contains

Contact Info: Name, email, phone
Conversations: Full conversation history
Events: Tracked events and page views
Sessions: Visit history with timestamps
Attributes: Custom data you've sent
Company: Associated company (if any)

API Operations

Get Visitor

const response = await fetch('/api/support/visitors/{visitorId}', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Response:

{
  data: {
    id: 'visitor-123',
    userId: 'user-123', // null if not identified
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
    avatarUrl: 'https://...',
    attributes: {
      plan: 'premium',
      company: 'Acme Inc'
    },
    location: {
      city: 'New York',
      country: 'US',
      timezone: 'America/New_York'
    },
    browser: {
      name: 'Chrome',
      version: '120.0.0'
    },
    os: {
      name: 'macOS',
      version: '14.0'
    },
    firstSeenAt: '2024-01-01T10:00:00Z',
    lastSeenAt: '2024-01-15T10:00:00Z',
    conversationCount: 5,
    sessionCount: 25
  }
}

List Visitors

const response = await fetch('/api/support/visitors', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data, meta } = await response.json();

Query parameters:

Parameter	Type	Description
`search`	string	Search by name or email
`identified`	boolean	Filter by identification status
`companyId`	string	Filter by company
`page`	number	Page number
`limit`	number	Items per page

Update Visitor

const response = await fetch('/api/support/visitors/{visitorId}', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    attributes: {
      plan: 'enterprise',
      accountManager: 'Jane Smith'
    }
  }),
});

Delete Visitor

const response = await fetch('/api/support/visitors/{visitorId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Session Tracking

Automatic Session Tracking

The widget automatically tracks:

Session start/end times
Pages viewed
Time on site
Referrer

Custom Page Tracking

For SPAs, manually track page views:

// When route changes
TransactionalSupport('trackPageView');
 
// With custom page name
TransactionalSupport('trackPageView', {
  page: '/dashboard',
  title: 'User Dashboard'
});

View Sessions

const response = await fetch('/api/support/visitors/{visitorId}/sessions', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Response:

{
  data: [
    {
      id: 'session-123',
      startedAt: '2024-01-15T10:00:00Z',
      endedAt: '2024-01-15T10:30:00Z',
      duration: 1800, // seconds
      pagesViewed: 5,
      pages: [
        { url: '/', title: 'Home', viewedAt: '...' },
        { url: '/pricing', title: 'Pricing', viewedAt: '...' }
      ]
    }
  ]
}

Event Tracking

Track Custom Events

// Track a purchase
TransactionalSupport('trackEvent', 'purchase_completed', {
  orderId: '12345',
  amount: 99.99,
  product: 'Pro Plan'
});
 
// Track feature usage
TransactionalSupport('trackEvent', 'feature_used', {
  feature: 'export_data',
  format: 'csv'
});

View Events

const response = await fetch('/api/support/visitors/{visitorId}/events', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Response:

{
  data: [
    {
      name: 'purchase_completed',
      properties: {
        orderId: '12345',
        amount: 99.99
      },
      timestamp: '2024-01-15T10:00:00Z'
    }
  ]
}

Segmentation

Create Segments

Group visitors by criteria:

const response = await fetch('/api/support/segments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    name: 'Premium Users',
    conditions: [
      { field: 'attributes.plan', operator: 'equals', value: 'premium' }
    ]
  }),
});

Query Segment

const response = await fetch('/api/support/segments/{segmentId}/visitors', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Data Privacy

Export all visitor data:

const response = await fetch('/api/support/visitors/{visitorId}/export', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Delete visitor and all their data:

const response = await fetch('/api/support/visitors/{visitorId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Anonymize Visitor

Remove PII but keep conversation history:

const response = await fetch('/api/support/visitors/{visitorId}/anonymize', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Merging Visitors

When a user signs up and you identify them, their anonymous visitor history merges automatically.

Manual Merge

Merge two visitor profiles:

const response = await fetch('/api/support/visitors/merge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    sourceVisitorId: 'anonymous-visitor',
    targetVisitorId: 'identified-user'
  }),
});

Next Steps

Companies - Company management
Conversations - Managing conversations
API Reference - Full API documentation