Visitor Identity API

Pass known user details to the Foxchat widget so logged-in visitors are automatically identified without filling out the pre-chat form.

Quick Start

Add a window.FoxchatSettings object before the widget script tag:

<script>
  window.FoxchatSettings = {
    name: "Jane Doe",
    email: "jane@example.com"
  };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

When these settings are present, the widget will skip the pre-chat form and immediately show the chat interface. The visitor's name and email will appear in your Slack thread.

API Reference

window.FoxchatSettings

At least name or email must be provided for auto-identification. If neither is set, the pre-chat form will be shown as usual.

Examples

Basic — name and email

<script>
  window.FoxchatSettings = {
    name: "Jane Doe",
    email: "jane@example.com"
  };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

With custom metadata

<script>
  window.FoxchatSettings = {
    name: "Jane Doe",
    email: "jane@example.com",
    metadata: {
      plan: "pro",
      userId: "u_123",
      company: "Acme Inc."
    }
  };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

Server-rendered (dynamic values)

If your site renders pages on the server (Next.js, Rails, Django, etc.), inject user data dynamically:

<!-- Example with server-side template variables -->
<script>
  window.FoxchatSettings = {
    name: "<%= current_user.name %>",
    email: "<%= current_user.email %>",
    metadata: {
      userId: "<%= current_user.id %>"
    }
  };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

React / SPA

For single-page apps, set the global before the widget script loads. If using a <script> tag in your HTML shell:

<!-- public/index.html -->
<script>
  // This will be set before the widget script runs
  window.FoxchatSettings = {
    name: "Jane Doe",
    email: "jane@example.com"
  };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

Or set it dynamically after login:

// After your user logs in
window.FoxchatSettings = {
  name: user.name,
  email: user.email
};

Note: If the widget has already loaded and created an anonymous session, the settings won't retroactively update the visitor. Set window.FoxchatSettings before the widget script runs for best results.

How It Works

1. When the widget loads, it checks for window.FoxchatSettings
2. If name or email is provided and no existing session is found, the widget automatically creates a visitor record with the supplied details
3. A conversation is started immediately — the pre-chat form is skipped entirely
4. The visitor's identity appears in your Slack threads so your team knows who they're talking to

Session Behavior

• Visitor sessions last 24 hours and are stored in the browser's localStorage
• If a session already exists (e.g., the visitor chatted earlier), the widget reuses it regardless of FoxchatSettings
• When the session expires, a new visitor will be created using the current FoxchatSettings values

Field Constraints

• name: Maximum 200 characters
• email: Maximum 320 characters, must be a valid email format
• metadata: Maximum 20 keys, each key and value up to 1000 characters. Both keys and values must be strings — numbers, booleans, arrays, and objects are not supported. Convert non-string values to strings:

// Correct
metadata: {
  userId: "123",
  active: "true",
  signupDate: "2026-01-15"
}

// Won't work — values must be strings
metadata: {
  userId: 123,
  active: true,
  tags: ["vip", "beta"]
}