# Add the Vocenya live chat to a website You are adding a third-party live chat widget to this website. It is one script tag. Follow these instructions exactly. ## What to add Add this script tag once, so it loads on every page, just before the closing `` tag (or the framework equivalent below): ```html ``` Replace `pk_YOUR_SITE_KEY` with the site key from the Vocenya portal (Live chat → Install). Each business has its own key. The chat bubble then appears in the corner of every page. Nothing else is required. ## Rules - Load the script once, site-wide, in the shared layout or template. Not per page and not twice. - Load it from https://vocenya.com/api/chat/widget.js exactly. Do not download, bundle, self-host, inline, minify or proxy the script: it is updated on our side. - Do not change, remove or invent the `data-key` value. - Keep `async` and do not add `type="module"`. - It is browser-only. Keep it out of server-only code paths (server components' logic, API routes, SSR data loaders, edge functions). Never call `window.Vocenya` during server rendering; call it only in the browser, from event handlers or effects. - Do not install an npm package for it: there is none. Do not add a chat component of your own. - If the site sends a Content Security Policy, add the sources below rather than loosening the policy any further. ## Where it goes, by framework ### Plain HTML or any server-rendered template Paste the tag just before `` in the template every page shares (footer include, base layout, `theme.liquid`, etc.). ### Next.js (App Router) In the root layout `app/layout.tsx`, use `next/script` with `strategy="afterInteractive"`, inside ``: ```tsx import Script from 'next/script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ``` ### Remix and React Router (framework mode) In `app/root.tsx`, inside `` next to ``: ```tsx ``` ### Webflow, Framer, Wix, Squarespace and other site builders Use the site-wide custom code setting, not a page embed: - Webflow: Site settings → Custom code → Footer code. Publish. - Framer: Site settings → General → Custom code → End of tag. Publish. - Wix: Settings → Custom code → Add custom code, All pages, Load once, Body - end. - Squarespace: Settings → Advanced → Code injection → Footer. - WordPress: use the Vocenya Chat plugin from the Vocenya portal, or the theme footer. ## Content Security Policy Only if the site sets a Content-Security-Policy (header or meta tag), add these sources to the existing directives: ``` script-src https://vocenya.com connect-src https://vocenya.com wss://ws.vocenya.com img-src https://vocenya.com frame-src https://vocenya.com ``` `connect-src` covers the chat API and the live-reply websocket. `frame-src` is only needed if you also embed the hosted chat page in an iframe. ## Optional: the JavaScript API Only if asked. To call the chat before the script has loaded, add this stub above the script tag; calls are queued and replayed: ```html ``` - `Vocenya('open')`, `Vocenya('close')`, `Vocenya('toggle')`: control the chat window. - `Vocenya('identify', { name, email, phone })`: prefill a signed-in visitor so the team sees who they are. - `Vocenya('on', 'message' | 'open' | 'close' | 'lead', callback)` and `Vocenya('off', event, callback)`: listen for chat events. A "Chat with us" button: ```html ``` Identify a logged-in user in React (browser only): ```tsx useEffect(() => { if (user) { window.Vocenya?.('identify', { name: user.name, email: user.email }); } }, [user]); ``` In TypeScript, declare it once: `declare global { interface Window { Vocenya?: (...args: unknown[]) => void } }`. ## Allowed domains The chat only runs on the domains listed under Live chat → Install in the Vocenya portal. Make sure the site's live domain is on that list; preview or staging domains (for example `*.lovable.app` or `*.vercel.app`) must be added too if the chat should work there. ## Check it worked 1. Publish or deploy the site. 2. Open the live site in a private window: a chat bubble appears in the corner. Click it and send a test message. 3. No bubble? Open the browser console: look for a blocked script or connection (Content Security Policy) or a domain that is not allowed. 4. Within a few minutes the Vocenya portal shows the chat as "Installed". ## When you are done Tell the owner which file you changed and confirm the script tag is unchanged. Docs: https://vocenya.com/developers/chat-install.md