# Visitor Identity API

Auto-identify logged-in users in the chat widget by passing their name, email, and metadata.

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`

| Field    | Type                            | Required | Description                                               |
|----------|---------------------------------|----------|-----------------------------------------------------------|
| `name`   | `string`                        | No       | Visitor's display name (max 200 characters)              |
| `email`  | `string`                        | No       | Visitor's email address (max 320 characters)             |
| `metadata` | `Record<string, string>`      | No       | Custom key-value pairs (max 20 keys, 1000 chars per value)|

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

### 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:

```javascript
// 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"]
}
```