Optimizing Chat and Web Widget (Classic) performance

<body>
<p id="docs-hc-snippet" style="display: none;">Using this setting, you can fine-tune your website for performance, while still leveraging all features on specific pages.</p>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>

<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

<div class="article-banner" id="support_all">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Team, Professional, or Enterprise</td>
</tr>
</tbody>
</table>
</div>

</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">
Verified AI summary <span id="up-triangle">◀</span><span id="down-triangle">▼</span>
</p>
<p id="docs-ai-summary-content">
Optimize your chat performance by using the <code>connectOnPageLoad</code>
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 <code>connectOnPageLoad</code> to <code>true</code>
or <code>false</code> in your page's source code to control when the
chat service connects, balancing performance with chat feature availability.
</p>
</div>

<div class="body">

<div class="p" dir="ltr">
<div class="note note">
<span class="notetitle">Note:</span> 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.</div>
You can use the <a class="xref" href="https://developer.zendesk.com/embeddables/docs/widget/settings#connectonpageload" target="_blank"><code class="ph codeph">connectOnPageLoad JavaScript
API</code></a> to defer the Chat connection until your visitor interacts with
the Web Widget. </div>
<p class="p" dir="ltr">Using this setting, you can fine-tune your website for performance, while still
leveraging all features on specific pages. </p>
<p class="p" dir="ltr">This article includes the following topics:</p>
<ul class="ul" id="topic_dbn_2cs_vjb__ul_kns_1xt_vjb">
<li class="li" dir="ltr"><a class="xref" href="#topic_lhq_2xt_vjb">Understanding the Web
Widget-Chat connection</a></li>
<li class="li"><a class="xref" href="#topic_iwk_2xt_vjb">Understanding the connectOnPageLoad
setting's impact</a></li>
<li class="li" dir="ltr">
<a class="xref" href="#topic_p3d_2xt_vjb">Adding connectOnPageLoad to
your web pages</a>
</li>
</ul>
<p class="p" dir="ltr">Related articles:</p>
<ul class="ul" id="topic_dbn_2cs_vjb__ul_qxd_lxt_vjb">
<li class="li" dir="ltr">
<a class="xref" href="https://developer.zendesk.com/embeddables/docs/widget/settings#connectonpageload" target="_blank">Developer documentation: ConnectOnPageLoad
setting </a>
</li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_lhq_2xt_vjb">
<h2 class="title topictitle2" id="ariaid-title2">Understanding the Chat-Web Widget (Classic) connection </h2>
<div class="body">
<p class="p" dir="ltr">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.</p>
<p class="p" dir="ltr">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:</p>
<ul class="ul" id="topic_lhq_2xt_vjb__ul_k1m_4xt_vjb">
<li class="li" dir="ltr">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 <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408821265178#topic_ttb_b4d_4fb" target="_blank">monitoring your website visitors</a>.</li>
<li class="li">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.</li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_iwk_2xt_vjb">
<h2 class="title topictitle2" id="ariaid-title3">Understanding the connectOnPageLoad setting's impact</h2>
<div class="body">
<p class="p">When you enable the <code class="ph codeph">connectOnPageLoad</code> 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.</p>
<p class="p" dir="ltr">However, using <code class="ph codeph">connectOnPageLoad</code> to defer the connection
comes with some important trade-offs to consider, before implementation.</p>
<p class="p"><strong class="ph b">When <code class="ph codeph">connectOnPageLoad = true</code>: </strong></p>
<div class="p">
<ul class="ul" id="topic_iwk_2xt_vjb__ul_xdy_2kn_yjb">
<li class="li">There is no impact on live chat functionality. The live chat experience is
the same as if there is no <code class="ph codeph">connectOnPageLoad</code> setting in the
page code.</li>
</ul>
</div>
<p class="p" dir="ltr"><strong class="ph b">When <code class="ph codeph">connectOnPageLoad = false</code>: </strong></p>
<ul class="ul" id="topic_iwk_2xt_vjb__ol_e4x_1yt_vjb">
<li class="li" dir="ltr">You will only be able to <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408821265178#topic_ttb_b4d_4fb" target="_blank">monitor visitors</a> who have initiated
chat or have clicked on the Web Widget (Classic).</li>
<li class="li" dir="ltr">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. </li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_p3d_2xt_vjb">
<h2 class="title topictitle2" id="ariaid-title4">Adding connectOnPageLoad to your web pages</h2>
<div class="body">
<div class="p">
<div class="div">You can add <code class="ph codeph">connectOnPageLoad</code> 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:<pre class="pre codeblock"><code>&lt;script type="text/javascript"&gt;
window.zESettings = {
webWidget: {
chat: {
connectOnPageLoad: false
}
}
};
&lt;/script&gt;</code></pre>
<p class="p" dir="ltr">The setting must be assigned a value, either true or false, which
determines how visitors are handled on each page:</p>
<ul class="ul" id="topic_p3d_2xt_vjb__ul_lwm_cyt_vjb">
<li class="li" dir="ltr">
<code class="ph codeph">connectOnPageLoad: true</code>: Connects to the Chat
service when the page loads, allowing you to engage with every visitor
on that web page. </li>
<li class="li" dir="ltr">
<code class="ph codeph">connectOnPageLoad: false:</code> 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. </li>
</ul>
</div>
</div>
<p class="p" dir="ltr"><strong class="ph b">To include the <code class="ph codeph">connectOnPageLoad</code> setting on your website</strong></p>
<ol class="ol" id="topic_p3d_2xt_vjb__ol_pky_fyt_vjb">
<li class="li" dir="ltr">In the source code of the web page, locate the Chat widget
code snippet.</li>
<li class="li" dir="ltr">Add the <a class="xref" href="https://developer.zendesk.com/embeddables/docs/widget/settings#connectonpageload" target="_blank"><code class="ph codeph">connectOnPageLoad</code>
setting</a> to your source code, above the Web Widget (Classic) code
snippet:
<pre class="pre codeblock"><code>&lt;script type="text/javascript"&gt;
window.zESettings = {
webWidget: {
chat: {
connectOnPageLoad: false
}
}
};
&lt;/script&gt;</code></pre>
</li>
<li class="li" dir="ltr">
Set the value of <code class="ph codeph">connectOnPageLoad</code> as <code class="ph codeph">true</code> or <code class="ph codeph">false</code>
depending on your use case.
</li>
<li class="li" dir="ltr">
Save and publish the page.
</li>
<li class="li" dir="ltr">
Repeat these steps on every page of your website with the
widget embedded.
</li>
</ol>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@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"
}
}</script><script id="ai-summary-script">
//<![CDATA[
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);
//]]>
</script>
</body>