1. Install the widget
Paste this before the closing </body> tag of every page. Your key is in Dashboard → Widget Settings.
<script src="https://visitorconnect.thechatnest.com/api/widget/script.js?key=YOUR_WIDGET_KEY" defer></script>That's it. The widget is isolated in a Shadow DOM, so your site's CSS can't break it and it can't break your site. It works on any domain, any framework, and needs no cookies.
2. Identify logged-in users
If your visitor is signed in, tell the widget who they are — they'll appear by name in the dashboard, with searchable history and any extra data you pass.
VisitorConnect.identify({
name: "Priya Sharma",
email: "priya@example.com",
phone: "+91 98765 43210", // optional
userId: "usr_42", // your own id
data: { company: "Acme Ltd", plan: "pro", orders: 12 }
});Identified people (and anyone who fills the pre-chat form) show up under Dashboard → Customers with their chats, lead score and a pipeline stage — export the list as CSV for your CRM.
Calling it before the script has loaded is fine — use the queue:
window.vcq = window.vcq || [];
vcq.push(["identify", { name: "Priya", email: "priya@example.com" }]);3. Track custom events
Events show up in the visitor's journey next to their page views.
VisitorConnect.track("added_to_cart");
VisitorConnect.track("checkout_started", "/checkout");
VisitorConnect.track("purchase", { amount: 1499, order_id: "A-1042" }); // see Revenue attributionRevenue attribution
On your order-success (or signup-success) page, report the sale. VisitorConnect links it to the visitor's most recent chat within 7 days and to the agent who handled it, so Analytics shows revenue from chats, per-agent sales, and the Customers page shows lifetime revenue per contact. A conversion webhook fires too.
VisitorConnect.track("purchase", { amount: 1499, currency: "INR", order_id: "A-1042" });
// also recognised: order, conversion, signup, subscribe, booking, lead — or any event with an amount4. JavaScript API
| Method | What it does |
|---|---|
VisitorConnect.open() | Open the chat panel (e.g. from your own "Chat with us" button) |
VisitorConnect.close() / toggle() | Close / toggle the panel |
VisitorConnect.identify(info) | Attach name, email, phone, userId and custom data (e.g. company) to the visitor |
VisitorConnect.track(name, urlOrData?) | Record a custom event |
VisitorConnect.startCall("audio" | "video") | Start a call from your own UI (a chat must be open first) |
VisitorConnect.isOpen() | Whether the panel is open |
<button onclick="VisitorConnect.open()">Chat with us</button>5. Single-page apps
Page changes made with history.pushState (React Router, Vue Router, Next.js, Angular) are tracked automatically — no extra code. Load the script once in your root layout.
6. Voice / video calls & screen sharing
Inside any active chat, the visitor can tap the phone or camera icon; agents can call from the chat room. Calls use WebRTC with our TURN relay, so they work behind corporate NATs and on mobile data. Available on the Pro plan and above.
Screen sharing works both ways: an agent can request the visitor's screen, or share their own to walk the visitor through something. The visitor always confirms before sharing.
7. Push notifications & the mobile app
In the dashboard sidebar, click Enable notifications to receive alerts for new chats, messages and incoming calls — even when the tab is closed. Click Install app (or "Add to Home Screen" on your phone) to run the dashboard as an app.
8. Allowed domains & security
In Widget Settings → Allowed websites, list the domains that may load your key (subdomains included). Requests from any other site are rejected with 403. Chat sockets are protected by signed, per-visitor tokens; the dashboard socket is locked to your own domain.
9. Webhooks
Get an HTTP POST when something happens. Configure endpoints under Dashboard → Webhooks and tick the events you want. Every request carries X-VisitorConnect-Event and an X-VisitorConnect-Signature header (HMAC-SHA256 of the body with your secret) so you can verify it. Works directly with Zapier, Make, n8n, Slack and Discord incoming webhooks.
| Event | When | Payload |
|---|---|---|
chat.created | A visitor starts a chat | room_id, visitor_name, visitor_email, subject |
message.new | Any text message (visitor or agent) | room_id, sender_type, sender_name, message, timestamp |
chat.closed | An agent ends the chat | room_id, visitor_name, agent, duration |
lead.hot | AI scores a chat ≥ 75 for purchase intent | room_id, visitor_name, lead_score, intent, sentiment, url |
offline.message | Offline form / contact form submitted | name, email, message |
9a. AI assistant (Gemini)
AI is on by default with VisitorConnect's built-in key (shared limits). For dedicated quota, paste your own free key from Google AI Studio under Widget & install → AI assistant, click Test, and choose which features to enable: auto-answer bot (with knowledge base and "Learn site"), smart replies, sentiment/intent/lead tags, summaries, live translation, coaching and the weekly topics report. Visitors can type human or tap Talk to a human at any time to reach your team.
10. Privacy & data
The widget stores one random session id in localStorage (no third-party cookies). We record page URLs, browser/OS, approximate country/city from the IP, and anything you pass to identify(). Page views are kept for 90 days; chats are kept as long as your account exists. See the Privacy Policy.
Need help? Contact us — or just open the chat on this page.