Custom Domain

Serve the chat widget from your own subdomain. Required for regions with internet restrictions and useful for bypassing ad-blockers.

Overview

Custom Widget Domain allows Enterprise organizations to serve the Next Cap chat widget through their own domain instead of api.nextcap.ai. This is essential for regions with internet restrictions where only whitelisted domains are accessible.

This feature is available on the Enterprise plan only. Contact sales to upgrade.

How It Works

When you configure a custom domain in the dashboard, the embed snippet shown in Settings → Install is updated to load from your domain. This update applies only to future copies of the snippet — any sites you have already deployed will continue loading the widget from api.nextcap.ai until you manually replace the script src and redeploy. For example, the snippet changes from:

Default embed codehtml

<script src="https://api.nextcap.ai/widget/loader.js" data-api-key="pk_live_..." defer></script>

To:

Custom domain embed codehtml

<script src="https://nextcap.yourdomain.com/widget/loader.js" data-api-key="pk_live_..." defer></script>

Once the custom domain is live, all subsequent widget traffic from that snippet (the loader, API calls, WebSockets, assets) routes through your domain. To stop restricted-region traffic from hitting api.nextcap.ai, you must locate every existing embed in your deployed sites, swap the src to the custom-domain URL shown above, and redeploy. Any page that is not updated will keep loading the widget from the default domain.

Setup Guide

Setting up a custom widget domain requires two steps: configuring a reverse proxy on your infrastructure, and entering the domain in the Next Cap dashboard.

Step 1 — Configure a reverse proxy

Your custom domain must proxy all incoming requests to api.nextcap.ai. This includes the widget script and all subsequent requests the widget makes. SSL must be enabled on your domain.

Nginx

# Maps the client's Upgrade header to a Connection value so WebSocket
# handshakes are forwarded correctly. Must be declared at the http {} scope,
# above the server { } block.
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name nextcap.yourdomain.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass https://api.nextcap.ai;
        proxy_set_header Host api.nextcap.ai;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_ssl_server_name on;

        # WebSocket support — the widget uses WSS for live chat / realtime
        # events. Without these, the WS handshake is stripped and live chat
        # silently fails behind the custom domain.
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Caddy

nextcap.yourdomain.com {
    reverse_proxy https://api.nextcap.ai {
        header_up Host api.nextcap.ai
    }
}

Cloudflare Worker

export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = "api.nextcap.ai";
    return fetch(new Request(url, request));
  }
};

Apache

# Requires Apache 2.4.47+ for the upgrade=websocket flag on mod_proxy_http.
# On older Apache, enable mod_proxy_wstunnel and add an explicit wss:// rule
# (ProxyPass /socket.io/ wss://api.nextcap.ai/socket.io/) before the catch-all.
<VirtualHost *:443>
    ServerName nextcap.yourdomain.com

    SSLProxyEngine On
    ProxyPreserveHost Off

    # upgrade=websocket forwards the WebSocket handshake frames so the widget's
    # live chat / realtime channel works through the custom domain.
    ProxyPass        / https://api.nextcap.ai/ upgrade=websocket
    ProxyPassReverse / https://api.nextcap.ai/

    RequestHeader set Host "api.nextcap.ai"
</VirtualHost>

Step 2 — Configure in dashboard

Go to Settings → General in your dashboard. Under Custom Widget Domain, enter your domain (e.g., nextcap.yourdomain.com) and save. Your embed code will automatically update to use the custom domain.

Verification

After setting up the reverse proxy and configuring the domain in the dashboard:

Open https://nextcap.yourdomain.com/widget/loader.js in your browser — you should see the widget JavaScript.
Check the embed code in your dashboard — it should show your custom domain in the script src.
Add the embed code to a test page and verify the widget loads and can send messages.

Troubleshooting

Widget script returns 502 or connection error

Your proxy cannot reach api.nextcap.ai. Ensure DNS resolves correctly and your proxy allows outbound HTTPS. If using nginx, make sure proxy_ssl_server_name on is set.

Widget loads but API calls fail

Ensure your proxy forwards all paths to api.nextcap.ai, not just specific routes. The widget makes additional requests beyond the initial script load.

SSL certificate errors

Your custom domain must have a valid SSL certificate. Use Let's Encrypt (free) or your existing certificate provider. Caddy handles SSL automatically.

Fonts or assets not loading

The widget loads fonts and assets from the same domain. Make sure your proxy forwards all /widget/* paths, not just the main script.

If your proxy is behind a CDN or firewall, ensure WebSocket connections are also proxied. Live chat and real-time features use WebSocket connections on the same domain.