Embed Snippet Reference

Complete reference for embedding the ZapTicket widget on your website.

Basic Installation

Add the following snippet before the closing </body> tag on every page where you want the chat widget to appear. The script loads asynchronously and never blocks page rendering.

Minimal embed

<script>
  window.ZapTicket = {
    siteKey: "zt_pub_YOUR_SITE_KEY"
  };
</script>
<script async src="https://cdn.zapticket.app/widget.js"></script>

💡Your public site key is available in the dashboard under Settings → API Keys. It starts with zt_pub_ and is safe to expose in client-side code.

Full Configuration Object

The window.ZapTicket object accepts the following properties. Only siteKey is required — all other fields are optional and have sensible defaults.

Complete configuration

<script>
  window.ZapTicket = {
    // Required: identifies your workspace
    siteKey: "zt_pub_abc123def456",

    // API base URL — only override for self-hosted deployments
    apiBaseUrl: "https://api.zapticket.app",

    // SignalR hub URL — only override for self-hosted deployments
    signalrUrl: "https://api.zapticket.app/hubs/chat",

    // Signed identity — verify the current user (see Identity docs)
    identity: {
      id: "user_12345",
      name: "Jane Doe",
      email: "[email protected]",
      hash: "a1b2c3d4e5f6..." // HMAC-SHA256 of the id using your secret key
    }
  };
</script>
<script async src="https://cdn.zapticket.app/widget.js"></script>

Configuration Options

`siteKey` (required)

Your workspace's public site key. This identifies which workspace the widget connects to. If the key is invalid or missing, the widget will not render and logs a console warning.

Type	`string`
Format	`zt_pub_*`
Required	Yes

`apiBaseUrl`

The base URL of the ZapTicket API server. Only override this if you're self-hosting ZapTicket. The widget appends paths like /widget/config and /widget/conversations to this URL.

Type	`string`
Default	`https://api.zapticket.app`
Required	No

`signalrUrl`

The URL of the SignalR hub used for real-time messaging. The widget establishes a persistent WebSocket connection (with automatic fallback to Server-Sent Events and Long Polling) to this endpoint for live chat updates.

Type	`string`
Default	`https://api.zapticket.app/hubs/chat`
Required	No

⚠️If you override apiBaseUrl, you almost always need to override signalrUrl as well. They should point to the same API server.

`identity`

An object representing the currently logged-in user on your site. When provided with a valid HMAC hash, the widget associates the conversation with that user's identity, enabling agents to see who they're talking to.

Field	Type	Required	Description
id	`string`	Yes	Unique identifier for the user in your system
name	`string`	No	Display name shown to agents
email	`string`	No	Email address shown to agents
hash	`string`	Yes	HMAC-SHA256 of the `id` using your workspace secret key

🚨The hash must be computed server-side using your workspace's secret key. Never expose the secret key in client-side code. See the Identity docs for implementation details.

Single Page Applications (SPA)

For React, Vue, Next.js, or other SPA frameworks, set window.ZapTicket before the widget script loads. If you dynamically set the identity after login, the widget will pick up changes when the user opens the chat — no page reload required.

React example (useEffect)

useEffect(() => {
  if (user) {
    window.ZapTicket = {
      siteKey: process.env.NEXT_PUBLIC_ZAPTICKET_SITE_KEY!,
      identity: {
        id: user.id,
        name: user.name,
        email: user.email,
        hash: user.zapticketHash // computed on your backend
      }
    };
  }
}, [user]);

Content Security Policy (CSP)

If your site uses a strict CSP, add the following directives:

Required CSP directives

script-src 'self' https://cdn.zapticket.app;
connect-src 'self' https://api.zapticket.app wss://api.zapticket.app;
frame-src 'self' https://cdn.zapticket.app;

Verifying the Installation

After adding the snippet:

Open your website in a browser and check the bottom-right corner for the chat bubble.
Open DevTools → Console. You should see no errors related to ZapTicket.
Open DevTools → Network. Confirm a successful request to /widget/config.
Click the bubble, send a test message, and verify it appears in your dashboard inbox.

If the widget doesn't appear, see the Troubleshooting guide.