The Zendesk Chat Web SDK

The widget you drop on a page is the easy 80%. The Zendesk Chat Web SDK around it is where the interesting behaviour lives.

Start free trial All guides

Sort out which thing you have first

Zendesk has shipped several web embeddables and the names overlap badly, which is why half the code samples online don't work on half the accounts.

The current one is the messaging widget: conversations persist across sessions and devices, bots can answer first, and threads become tickets in the agent workspace. The older classic Web Widget and the separate Chat Web SDK behaved differently, were scripted differently, and are still described in plenty of tutorials.

Before you write a line of integration code, confirm which embeddable your account serves and read the API reference for that one specifically. The method names and the global object differ between them, and guessing wastes a day.

Getting it on the page

Installation is one script tag carrying a key that identifies your account and brand, placed before the closing body tag.

<script id="ze-snippet"
  src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY">
</script>

That is a working widget. Three things to get right beyond it. Load the script exactly once, because single page apps that re-inject it on every route change end up with several launchers and duplicated event handlers. If you deploy through a tag manager, check the widget still loads for visitors who declined analytics cookies, since a support widget is arguably functional rather than marketing. And test on a phone before you ship, where an open widget takes most of the screen.

What the Zendesk Chat Web SDK can do

Commands go through a global function that the snippet defines. The current messaging widget uses a call shaped roughly like zE('messenger', 'open'), while the older widgets used different namespaces entirely. Treat exact method names as something to look up rather than remember, and check the current Zendesk developer docs.

The capabilities are stable even when the syntax is not.

Show, hide, open and close. Drive the widget from your own button instead of the default launcher, or hide it entirely on pages where nobody is staffed.

Set visitor context. Pass a name and email so the conversation attaches to a person rather than an anonymous session.

Listen for events. Widget opened, message received, unread count changed. Useful for your own badge or analytics.

Set locale. Force a language rather than relying on browser detection.

Log out and clear the session. Essential on shared computers and forgotten constantly.

Adjust position offsets. So the launcher does not sit on your cookie banner.

Authentication is the part worth doing properly

An unauthenticated widget creates a new end user, or none at all, every time somebody clears their cookies. Run that for six months and one customer exists in your account four times with four fragments of history.

When a visitor is signed in to your product, authenticate the widget with a signed token generated on your server. Your back end signs a payload identifying the user with a shared secret, the page passes it to the widget, and the conversation attaches to their real Zendesk profile.

Sign it server side. Always. A secret shipped to the browser is not a secret, and anyone can then open a session as any customer you have.

The mistakes that cost a day each

Four, in rough order of how often they happen.

Calling the API before the widget is ready. The snippet loads asynchronously. Commands fired on page load, before initialisation finishes, silently do nothing. Queue them or wait for the ready callback the current docs describe.

Re-initialising on route change. Covered above and worth repeating, because in a single page app it produces bugs that look like anything except what they are.

Hiding the launcher and forgetting to show it again. Hide it on checkout, navigate away, and the visitor now has no support anywhere on your site. Set visibility explicitly per route rather than hiding once and hoping.

Testing only while signed in. Half your traffic is anonymous. The anonymous path is the one that creates junk end user records, so test it deliberately, in a private window, at least once per release.

Worth adding one habit: log widget errors to your own monitoring. An embeddable that fails silently on a subset of browsers is invisible until somebody complains that chat has been broken for weeks.

How far customisation goes

In the admin interface: colours, launcher label, brand name and avatar, offline behaviour, which bot answers first, and language. No deployment needed for any of it.

In code: everything in the API list above.

What you cannot do is redesign it. The widget renders in an iframe with a supported set of options, and your page CSS doesn't reach inside. If a designer hands you a bespoke chat interface, you're no longer customising a widget, you are building a client against the messaging APIs. That's a real project with a real budget and an ongoing maintenance commitment, and it is occasionally the right call for a product where chat is core.

Placement and volume trade-offs are covered in the chat widget guide.

FAQ

Frequently asked questions

What can the widget JavaScript API control?

Visibility, prefilled fields, identity and events. The Zendesk web widget API and the Zendesk chat widget API are the same surface at different generations, and the Zendesk widget JavaScript API is what you use to open the widget from your own button.

What is the Zendesk chat web SDK?

The JavaScript interface around the embeddable web widget, used to open, hide, prefill and authenticate it from your own site code. Naming has changed across widget generations, so match the docs to your account.

How do I open the Zendesk widget from my own button?

Call the widget API from your click handler rather than relying on the default launcher, and hide the launcher if you want your button to be the only entry point.

Can I identify signed-in users in the widget?

Yes, with a token signed on your server. That attaches conversations to the existing Zendesk profile instead of creating a new anonymous end user each session.

Can I restyle the widget with CSS?

Only within the supported settings. It renders inside an iframe and your page stylesheet cannot reach it. A fully custom interface means building against the messaging APIs.

Why do the code samples I find online not work?

They are usually written for a different widget generation. Confirm which embeddable your account uses, then follow the developer docs for that one.