This is the technical guide to install the Customerly live chat on any website or web app. It works on every domain and with any framework. Using React or Next.js? Use the official package: Install Customerly in React and Next.js. Built your app with Lovable, Bolt, v0, Replit, Cursor or Claude Code? See Add Customerly to an app built with AI.
Install the snippet
Add this code just before the </body> tag of every page. Replace ADD YOUR PROJECT ID with the Project ID from Settings → Installation → Install messenger.
<script>
!function(){var e=window,i=document,t="customerly",n="queue",o="load",r="settings",u=e[t]=e[t]||[];if(u.t){return void u.i("[customerly] SDK already initialized. Snippet included twice.")}u.t=!0;u.loaded=!1;u.o=["event","attribute","update","show","hide","open","close"];u[n]=[];u.i=function(t){e.console&&!u.debug&&console.error&&console.error(t)};u.u=function(e){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(e),u[n].push(t),u}};u[o]=function(t){u[r]=t||{};if(u.loaded){return void u.i("[customerly] SDK already loaded. Use `customerly.update` to change settings.")}u.loaded=!0;var e=i.createElement("script");e.type="text/javascript",e.async=!0,e.src="https://messenger.customerly.io/launcher.js";var n=i.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)};u.o.forEach(function(t){u[t]=u.u(t)})}();
customerly.load({
"app_id": "ADD YOUR PROJECT ID"
});
</script>This is all you need on a public landing page. Visitors who chat or leave their email become leads.
Complete example for a web app with logged-in users
customerly.load({
app_id: "ADD YOUR PROJECT ID",
user_id: "USER_ID_FROM_YOUR_DATABASE", // stable, unique per user
name: "Jane Doe",
email: "jane@example.com",
email_hash: "HMAC_SHA256_OF_LOWERCASED_EMAIL", // only if Identity Verification is on, generated on your server
attributes: {
plan: "pro",
created_at: 1384902000, // dates as Unix timestamps (seconds)
license_expire_at: 1603490400
},
company: {
company_id: "COMPANY_ID",
name: "ACME"
}
});Why identify your users
Every user you identify is created in Customerly automatically and appears in the New users list: your app's signups are synced with no import.
Your team and Aura, the AI agent, see who is writing and their attributes, so answers are specific.
You can filter users by any attribute or event, save segments, and send newsletters, product updates and targeted campaigns: see Send newsletters and targeted emails to the users of your app.
Live chat user authentication
If your platform knows the user (name, email, user ID), pass it to customerly.load(). Users are then authenticated automatically and you know who is contacting you.
customerly.load({
app_id: "ADD YOUR PROJECT ID",
user_id: "REPLACE WITH YOUR USER ID", // Optional
name: "REPLACE WITH USER NAME",
email: "REPLACE WITH USER EMAIL"
});Replace the placeholder strings with the real user data. If you leave placeholders, all your users will share the same ID and the same conversations.
To prevent impersonation, enable Identity Verification and add email_hash, generated on your server: see Setting up Identity Verification.
Live chat additional user data
To track any user information, add the attributes object to customerly.load(). It is a key/value object you can extend as much as you need.
customerly.load({
app_id: "ADD YOUR PROJECT ID",
user_id: "REPLACE WITH YOUR USER ID", // Optional
name: "REPLACE WITH USER NAME",
email: "REPLACE WITH USER EMAIL",
// Custom attributes of the user you want to track
attributes: {
created_at: 1384902000, // Add dates as Unix timestamp
license_expire_at: 1603490400,
plan: "pro"
}
});Track companies for users
To track the company of each user, add the company object to your load function:
company: {
company_id: "COMPANY_ID",
name: "ACME",
// Custom company properties
address: "Ground Floor, 71 Lower Baggot Street",
city: "Dublin",
employees: 10,
admin_url: "https://www.company.com/admin/companyID",
sub_name: "Pro",
sub_period: "Yearly",
sub_state: "Active",
sub_amount: 1188,
sub_currency: "EUR",
last_payment_amount: 1188,
total_revenues: 5940,
domain: "company.com"
},Live chat data update
To update any user value, call update() with the same object you pass to load(). In single-page apps (React, Vue, Next.js), also call it on every route change.
customerly.update({ ... }) // Same values as loadRegister Lead
To register a lead from a form (waitlist, newsletter box, contact form), use registerLead and pass any data.
customerly.registerLead(email, {
name: "Luca",
last_name: "Micheli",
company_size: 1000
});Customization options
Add these options to customerly.load() when you need them.
Position
direction: "right" // or "left"The widget always sits at the bottom; you can move it left or right. To change the distance from the bottom and the side:
customerly.load({
app_id: "ADD YOUR PROJECT ID",
position: {
desktop: { bottom: 50, side: 50 },
mobile: { bottom: 30, side: 30 }
}
});Accent and contrast colour
accentColor: "#ffffff", // any HEX code
contrastColor: "#000000"Visibility
visible: true, // hide on certain pages with false
visibleOnMobile: false // hide only on mobileLocalization
The live chat detects the user's language automatically. To force the main language set in your dashboard:
autodetectLocale: falseAttachments
attachmentsAvailable: false // hide the clip iconDisable CSSOM injection
If you have CSS styling problems, disable the styled-components speedy mode (CSSStyleSheet JS API):
disableCSSOMInjection: trueCustom functions
customerly.show(); // show the live chat (if hidden with visible: false)
customerly.hide(); // hide the live chat
customerly.open(); // open the live chat home, like a click on the bubble
customerly.close(); // close the live chat
customerly.event("name"); // fire an event, e.g. on a button click
customerly.attribute("key", "value"); // add or change an attribute on the go
customerly.logout(); // log the user out of the messenger (call it when the user signs out of your app)
customerly.showBookMeeting(); // open your meeting calendar (set it up in project settings first)More on logout: Log out a user from the live chat.