Chat Widget
Integration Guide
The Daman Markets Helpdesk Chat Widget is a lightweight, self-contained JavaScript widget that embeds into any web application with a single script tag. It connects clients to the Daman Markets support team via Zendesk Sunshine Conversations and provides full chat session history.
.js file. Drop in one script tag and two lines of JavaScript — you're done.
Quick Start
Add the following snippet to the <head> or bottom of <body> on every page where the widget should appear.
<!-- Step 1: Load the widget script (non-blocking) -->
<script src="https://helpdesk.damanmarkets.com/chat-widget.js" defer></script>
<!-- Step 2: Initialise on page load -->
<script>
document.addEventListener('DOMContentLoaded', function() {
const timer = setInterval(function() {
if (window.initDamanChat) {
clearInterval(timer);
window.initDamanChat();
}
}, 100);
});
</script>That's it. The widget will appear as a floating button in the bottom-right corner of the page.
How It Works
The widget supports two modes based on whether the client's identity is known to your application.
● Registered Client
Your website provides the client's email and name via window.damanClient. The widget opens directly to their full chat history — no form required.
● Guest Client
No client identity is set. The widget shows a short form for the client to enter their name and email before accessing support and their session history.
Client opens the widget
The floating chat button is clicked.
Identity check
The widget reads window.damanClient.email. If present → registered flow. If null/absent → guest flow (pre-chat form shown).
Session history loads
All past chat sessions (active, inactive, ended) are fetched from Zendesk Sunshine and displayed as a list with status badges.
Client selects or starts a chat
They can open any historical session or click + Start New Chat to begin a fresh conversation with a support agent.
Registered Clients
For authenticated users, set window.damanClient with the user's details before the widget script loads. The widget reads this variable automatically — no function arguments needed.
<script> block to output the signed-in user's data into window.damanClient. Never hardcode email addresses in your frontend source.
<!--
Step 1: Output the signed-in user's identity.
Render this block from your server using your session/auth system.
Examples: Django {{ user.email }}, Laravel {{ Auth::user()->email }},
.NET @User.FindFirst("email")?.Value
-->
<script>
window.damanClient = {
name: "{{ session.user.fullName }}",
email: "{{ session.user.email }}",
phone: "{{ session.user.phone }}", // optional
language: "{{ session.user.language }}" // "English" or "Arabic"
};
</script>
<!-- Step 2: Load the widget script -->
<script src="https://helpdesk.damanmarkets.com/chat-widget.js" defer></script>
<!-- Step 3: Initialise -->
<script>
document.addEventListener('DOMContentLoaded', function() {
const t = setInterval(function() {
if (window.initDamanChat) {
clearInterval(t);
window.initDamanChat();
}
}, 100);
});
</script>Framework Examples
<script>
window.damanClient = {
name: "@User.FindFirst("name")?.Value",
email: "@User.FindFirst("email")?.Value"
};
</script><script>
window.damanClient = {
name: "{{ Auth::user()->name }}",
email: "{{ Auth::user()->email }}"
};
</script>// In _app.js or layout.js, after auth is resolved:
window.damanClient = {
name: session.user.name,
email: session.user.email
};
window.initDamanChat();Guest / Public Pages
On public or unauthenticated pages, simply do not set window.damanClient. The widget automatically detects the absence and shows a short pre-chat form to collect the visitor's name and email before opening support.
<!-- Do NOT set window.damanClient on public pages -->
<script src="https://helpdesk.damanmarkets.com/chat-widget.js" defer></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
const t = setInterval(function() {
if (window.initDamanChat) {
clearInterval(t);
window.initDamanChat();
}
}, 100);
});
</script>Direct Full-Screen Widget
For mobile applications or dedicated support pages, you can use the direct-load version of the widget. This version skips the floating icon and renders the chat interface immediately upon page load.
<!-- Use chat_widget.js (underscore) for direct mode -->
<script src="https://helpdesk.damanmarkets.com/chat_widget.js" defer></script>// Step 1: Prepare auth object from your system
const authData = {
token: "USER_JWT_TOKEN",
email: "client@example.com",
name: "John Smith"
};
// Step 2: Save to localStorage (read by direct widget)
localStorage.setItem('customerAuth', JSON.stringify(authData));
// Step 3: Load the direct widget
const s = document.createElement('script');
s.src = "https://helpdesk.damanmarkets.com/chat_widget.js";
document.body.appendChild(s);Configuration Reference
The window.damanClient object accepts the following properties.
| Property | Type | Required | Description |
|---|---|---|---|
| string | Required | The client's email address. Used to look up their Zendesk account and session history. Without this, the widget falls back to guest mode. | |
| name | string | Optional | The client's display name. Shown in chat messages and within the Zendesk agent interface. |
| phone | string | Optional | The client's phone number (e.g. +971501234567). Stored on the Zendesk user profile. |
| language | string | Optional | Interface language. Accepted values: "English" or "Arabic". Defaults to "English". |
JavaScript API
window.initDamanChat()
Mounts the widget on the page. Call this once after the script has loaded. Accepts no arguments — it reads identity from window.damanClient automatically.
| Method | Description |
|---|---|
| window.initDamanChat() | Mounts and initialises the widget. Safe to call multiple times — only mounts once. |
| window.damanClient | Identity object read on widget init. Must be set before calling initDamanChat(). |
window.damanClient before window.initDamanChat() is called. If you're using defer on the script tag, a setInterval poll (as shown in the examples above) ensures the widget is ready before initialising.
Security
Never expose sensitive data in frontend JavaScript
Only pass non-sensitive profile data into window.damanClient: name, email, phone, and language. Do not pass API keys, session tokens, or internal IDs.
Server-side rendering
Always render the window.damanClient block from your server using data from a validated, authenticated session. Never let client-side JavaScript construct the identity object from URL parameters or unverified sources.
HTTPS required
The widget script must be loaded over HTTPS in production. Mixed-content (HTTP script on an HTTPS page) will be blocked by modern browsers.
window.damanClient.email property must always come from a live, server-side authentication context — not from a static string in your source code.
Session Behavior
sessionStorage persistence
Once a user completes the pre-chat form (guest flow) or logs in (registered flow), their identity and conversation state are stored in sessionStorage. This means:
- Returning users within the same browser tab skip the form automatically.
- Opening a new tab or window starts a fresh session.
- Closing the browser clears the session.
Chat history
When the widget opens, it calls GET /api/chat/sessions?email=... and retrieves all historical conversations from Zendesk Sunshine. Sessions are displayed with the following status badges:
| Status | Meaning |
|---|---|
| ● Active | Session updated within the last 24 hours. |
| ◉ Inactive | Session older than 24 hours but not closed. |
| ○ Ended | Session has been resolved or closed. |
Troubleshooting
Widget button is not appearing
Ensure the script URL is reachable from your domain and that there are no Content Security Policy (CSP) headers blocking it. Check the browser console for errors.
Sessions not loading for registered clients
Verify that window.damanClient.email is set to the exact email address used in the client's Zendesk profile. Check the network tab for the /api/chat/sessions response.
Pre-chat form keeps appearing for returning users
This happens when sessionStorage is cleared between visits (e.g. private/incognito browsing). For registered clients, ensure window.damanClient is always set server-side so the form is bypassed regardless of stored state.
Widget is loading but shows blank content
Open the browser console and check for JavaScript errors. Ensure there is no CSS rule on your page overriding display, height, or overflow on the widget container (selector: #daman-chat-widget).