Skip to main content
This widget is being rolled out. Interfaces on this page may change before general availability. The engineering documentation site, which tracks the current build, is at webchat.connectly.ai/docs.
The widget fails quietly more often than it fails loudly, which is what makes these worth naming.

​
The launcher appears, but chat does not work — or it looks unstyled

Check the client key first. An unrecognized or revoked key makes the widget fall back to a default appearance and fail to start a conversation, without stopping the launcher from rendering. So a launcher on the page proves the script loaded; it proves nothing about the key. Turn logging up (below) and look in the console for a warning naming the client key, or a “widget config unavailable” / “unknown or inactive” message.

​
A key I just created looks broken for the first minute

Expected, not a bug. A newly issued key can take up to 60 seconds to become active everywhere, and a revoked key can likewise take up to 60 seconds to actually stop working. Wait a minute and reload before concluding the integration is wrong — and do not treat a revocation as an incident response tool on its own.

​
npm cannot install the git URL

If HTTPS asks for credentials, the two variants that usually help:
Repository not found, or a credential prompt that will not take your password, almost always means the token lacks read access to the repository — not that the tag is wrong.

​
Two launchers, or a transcript that splits in half

You have two integrations on one page — almost always the paste-in <script> and the npm package, one of them added by a tag manager or a theme rather than by you. Nothing errors, because multiple widgets on one page is a supported case. Search the rendered page for both webchat2026.min.js and any bundled import of @connectly/webchat, and remove one.

​
ReferenceError: HTMLElement is not defined at build or boot

The package was imported on the server. The import itself throws, before any component renders, because the module defines a custom element extending HTMLElement. This includes @connectly/webchat/react, and it includes a Next.js client component, which is still prerendered during next build. The fix is a browser-only import path — see “Server rendering” under Install.

​
Vue warns on every render, or Angular throws NG0304

Both mean the framework does not know <connectly-webchat> is a custom element.
  • Vue — add isCustomElement to the compiler options.
  • Angular — add CUSTOM_ELEMENTS_SCHEMA to the component’s schemas.
Vue’s failure is the nastier of the two: it warns rather than throwing, and emits no element at all, so the page comes up looking like the script simply did not load.

​
The element moved itself into <body> and my framework broke

An ancestor with a transform, filter or contain becomes the containing block for position: fixed, so the element relocates itself to <body> — and a framework that still thinks it owns that node will throw on the next update. Append the element to <body> yourself, or use the React wrapper, which expects it.

​
More logging

Raise the console verbosity of a production build:
That separates “wrong key” from “wrong integration” from “network”: you see whether the config loaded, whether a session minted, and whether the socket connected.

​
Support

Escalate through your usual Connectly channel with the widget version (window.ConnectlyWebchat.version, or the exported WEBCHAT_ELEMENT_VERSION) and your client key, plus a console log captured at log-level="debug".