Optimizing Chat and Web Widget (Classic) performance


Using this setting, you can fine-tune your website for performance, while still leveraging all features on specific pages.


What's my plan?







All Suites

Team, Growth, Professional, Enterprise, or Enterprise Plus










Support

Team, Professional, or Enterprise








Verified AI summary ◀▼


Optimize your chat performance by using the connectOnPageLoad
JavaScript API to delay chat connections until users interact with the
Web Widget. This approach can enhance page load speed and manage high
traffic better. Set connectOnPageLoad to true
or false in your page's source code to control when the
chat service connects, balancing performance with chat feature availability.







Note: This article is provided for instructional purposes only. Zendesk does
not support or guarantee the code. Please post any issues you have in the comments
section or try searching for a solution online.
You can use the connectOnPageLoad JavaScript
API to defer the Chat connection until your visitor interacts with
the Web Widget.
Using this setting, you can fine-tune your website for performance, while still
leveraging all features on specific pages.
This article includes the following topics:

Understanding the Web
Widget-Chat connection
Understanding the connectOnPageLoad
setting's impact

Adding connectOnPageLoad to
your web pages


Related articles:


Developer documentation: ConnectOnPageLoad
setting




Understanding the Chat-Web Widget (Classic) connection

By default, Web Widget (Classic) connects to live chat services on page load for
any page where the widget snippet is embedded AND Chat is enabled.
The timing of this connection makes features like proactive chat and
conversion tracking possible. However, it can negatively affect performance in a
number of ways:

If you have high visitor traffic volume, these connections can reduce
the performance of your chat product, and make it more difficult to identify
customers when monitoring your website visitors.
It impacts Web Widget (Classic) performance. Connecting to live chat on page load
means that more assets need to be delivered, before the Web Widget (Classic) is
interactive on a web page. This can impact your overall web page load
speed.




Understanding the connectOnPageLoad setting's impact

When you enable the connectOnPageLoad setting, there should be no noticeable impact
on the end user experience. There may be a slight delay of one to two seconds (at
the most) when a customer opens the widget.
However, using connectOnPageLoad to defer the connection
comes with some important trade-offs to consider, before implementation.
When connectOnPageLoad = true:


There is no impact on live chat functionality. The live chat experience is
the same as if there is no connectOnPageLoad setting in the
page code.


When connectOnPageLoad = false:

You will only be able to monitor visitors who have initiated
chat or have clicked on the Web Widget (Classic).
Some of the live chat features may be impacted, such as conversion
tracking, proactive triggers, and Web Widget (Classic) JS APIs which rely on
visitors' connections with Chat services.




Adding connectOnPageLoad to your web pages


You can add connectOnPageLoad to any page with the embedded
Web Widget (Classic). The setting is added to the source code on each web page,
as in the following
example:
window.zESettings = {
webWidget: {
chat: {
connectOnPageLoad: false
}
}
};

The setting must be assigned a value, either true or false, which
determines how visitors are handled on each page:


connectOnPageLoad: true: Connects to the Chat
service when the page loads, allowing you to engage with every visitor
on that web page.

connectOnPageLoad: false: Connects to the
Chat service when a user interacts with the widget, allowing you to
focus on visitors currently chatting with agents, or who have initiated
a chat.



To include the connectOnPageLoad setting on your website

In the source code of the web page, locate the Chat widget
code snippet.
Add the connectOnPageLoad
setting to your source code, above the Web Widget (Classic) code
snippet:

window.zESettings = {
webWidget: {
chat: {
connectOnPageLoad: false
}
}
};



Set the value of connectOnPageLoad as true or false
depending on your use case.


Save and publish the page.


Repeat these steps on every page of your website with the
widget embedded.




{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408820305562",
"url": "https://support.zendesk.com/hc/en-us/articles/4408820305562",
"headline": "Optimizing Chat and Web Widget (Classic) performance",
"description": "You can optimize your website's chat widget performance by using the connectOnPageLoad setting to control when the chat service connects, either on page load or upon user interaction.",
"articleSection": "Web Widget (Classic) documentation",
"datePublished": "2021-10-16T03:29:30+00:00",
"dateModified": "2026-04-17T21:52:50.096094+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408820305562"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}
//
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//

