Widget Troubleshooting

Widget Not Appearing

If the chat bubble doesn't show up on your page, work through these checks:

1. Verify the embed snippet is present

View source on your page and confirm both the config object and the script tag are present before </body>:

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

2. Check the browser console

Open DevTools → Console and look for error messages. Common ones:

• ZapTicket: Invalid site key — the site key doesn't match any workspace. Double-check you're using the public key (starts with zt_pub_).
• ZapTicket: Failed to load config — network request to /widget/config failed (likely CORS or connectivity issue).
• Refused to load script — Content Security Policy is blocking the widget script.

3. Check z-index conflicts

The widget renders at z-index: 2147483647 (max value). If another element on your page uses the same value and covers the bottom corner, the bubble may be hidden. Inspect the area with DevTools to check for overlapping elements.

4. Check for duplicate embeds

Including the widget script more than once can cause initialization failures. Ensure you only have one window.ZapTicket assignment and one script tag per page.

CORS Errors

If you see errors like Access to fetch has been blocked by CORS policy in the console, the API server is not allowing requests from your domain.

For hosted (cloud) ZapTicket

The cloud API allows requests from all origins by default. If you're seeing CORS errors:

• Ensure you're not overriding apiBaseUrl to a wrong address.
• Check that your request isn't being intercepted by a proxy, VPN, or browser extension.
• Verify the CDN script URL is exactly https://cdn.zapticket.app/widget.js.

For self-hosted ZapTicket

You need to configure CORS in your API server to allow your website's origin. In appsettings.json:

{
  "Cors": {
    "AllowedOrigins": [
      "https://www.yoursite.com",
      "https://yoursite.com"
    ]
  }
}

Site Key Invalid

The error ZapTicket: Invalid site key means the API couldn't find a workspace matching your key. Common causes:

• Wrong key type: You might be using the secret key (zt_sk_*) instead of the public key (zt_pub_*). The widget requires the public key.
• Key was regenerated: If you regenerated your API keys in the dashboard, the old public key is invalidated. Update your embed snippet with the new key.
• Copy-paste error: Ensure no extra whitespace or missing characters in the key.
• Wrong environment: If you have separate staging and production workspaces, make sure you're using the correct workspace's key for each environment.

How to verify your key

curl -I https://api.zapticket.app/widget/config \
  -H "X-Site-Key: zt_pub_YOUR_KEY_HERE"

# 200 = valid key
# 401 = invalid key

Connection Drops / Reconnection Issues

The widget uses SignalR (WebSocket with fallback) for real-time communication. Intermittent disconnections are normal on mobile networks, but persistent drops indicate a configuration or infrastructure issue.

Symptoms

• Messages sent by the visitor aren't delivered to the agent.
• Agent replies arrive late or not at all.
• Console shows WebSocket connection failed or SignalR: reconnecting repeatedly.

Common causes and fixes

Nginx WebSocket configuration

location /hubs/ {
    proxy_pass http://api_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_read_timeout 120s;
}

Widget Loads But Chat Doesn't Work

If the bubble appears but sending messages fails or the chat panel is empty:

• Check network tab: Look for failed requests to /widget/conversations or the SignalR negotiate endpoint.
• Mixed content: If your site is HTTPS but the API URL is HTTP, the browser blocks the requests. Ensure all URLs use HTTPS.
• Ad blockers: Some aggressive ad blockers flag chat widgets. Test in an incognito window with extensions disabled.
• CSP headers: Ensure your Content Security Policy allows connections to the API domain. See the embed reference for required CSP directives.

Identity Verification Failing

If conversations show as "Anonymous Visitor" despite passing an identity object, the HMAC verification is failing silently. Check:

• You're using the Identity Secret Key (zt_isk_*), not the API secret key.
• You're hashing only the id field, not a concatenation of id + name + email.
• The hash is hex-encoded (lowercase), not base64.
• There's no whitespace or encoding mismatch between what you hash server-side and what you pass to the widget.

See the Identity documentation for complete implementation examples.

Still Stuck?

If none of the above resolves your issue:

1. Open DevTools → Console and Network tabs, reproduce the issue, and note any errors.
2. Check the API server logs for corresponding error entries.
3. Reach out to support with: your site key, the page URL, browser/OS, and any console errors.