API

Connectly Webchat is in development

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.

Which API you get depends on which integration you chose.

The script tag publishes a page global, window.ConnectlyWebchat.
The npm package publishes none — the element itself is the API. Reach it from outside your component tree with document.querySelector('connectly-webchat').

`window.ConnectlyWebchat` — script tag only

The global is published when the widget bundle executes, so it exists in any tag that runs after the bundle’s — a defer or type="module" tag — and not in a plain inline script. A plain inline script runs during parsing, and the bundle carries defer, so the inline one runs first no matter where on the page you put it. Where you cannot rely on tag order, register a connectly-webchat:ready listener on document (the event bubbles, and fires when the launcher renders — it is not replayed for a listener added later) and use the global from inside that, or place <connectly-webchat> declaratively and skip the global entirely.

window.ConnectlyWebchat: {
  init(options): Element | null;
  destroy(): void;
  open(): void;
  close(): void;
  toggle(): void;
  isOpen(): boolean;
  isMounted(): boolean;
  element(): Element | null;
  version: string;
}

init(options) accepts:

option	meaning
`clientKey`	Required.
`title`	The panel heading.
`width`, `height`	Panel size. A bare number (`380`) or a px string (`'380px'`) both work; any other unit is dropped with a console warning.
`logLevel`	`silent` \| `error` \| `warn` \| `info` \| `debug`.
`config`	Presentation overrides — the same object the npm package’s `config` prop takes.
`open`	Open the panel as soon as it is ready, instead of waiting for a click.
`onMountedChange`	Called with `true`/`false` as the widget is added to / removed from the page.
`onOpenChange`	Called with `true`/`false` as the panel opens/closes. This is the one you want for a toggle button’s label.

Calling init() twice does not create a second widget. It returns the existing element and applies any new options to it — except clientKey, which cannot be changed on a live widget. Remove the old integration first if you need a different key. isMounted() asks whether the widget is on the page at all (true from shortly after init() until destroy()); isOpen() asks whether the panel is showing. isOpen() is almost always the one you want, paired with onOpenChange.

`<connectly-webchat>` — both integrations

The element is registered by the script tag and by the package’s import alike, and it is the whole API on the npm path. See Configure for the attribute list.

const el = document.querySelector('connectly-webchat');
el.openPanel();
el.closePanel();
el.toggle();
el.open;   // boolean, reflected to the attribute
el.config = { theme: { accent: '#c026d3' } };
el.reload(); // `config` is a plain field; assigning it repaints nothing on its own

In React, prefer the declarative open / onOpenChange props over reaching for the element — the wrapper’s onOpenChange is exactly the element’s :open and :close events on its own node.

Opening and closing the panel

The names differ by path — open() / close() exist only on the script tag’s page global, and the element’s methods are openPanel() / closePanel() — but they are equivalent: the global delegates to the element.

// React, declaratively:
<ConnectlyWebchat clientKey="<your-client-key>" open={isOpen} onOpenChange={setIsOpen} />

Events

Events are dispatched on the element and are bubbles / composed, so a page-level listener works without holding a reference to the element:

document.addEventListener('connectly-webchat:open', (e) => {
  console.log(e.detail);
});

event	when
`connectly-webchat:ready`	The launcher has rendered. Carries the widget version and `configSource`, which is `default` when the config had not arrived yet.
`connectly-webchat:open`	The panel opened, whoever caused it.
`connectly-webchat:close`	The panel closed, whoever caused it.
`connectly-webchat:error`	Something failed hard enough to stop the conversation.
`connectly-webchat:config-warning`	A config value was rejected or ignored.

Payloads are on event.detail — see WebchatElementEventDetail in the package’s types.

Version

WEBCHAT_ELEMENT_VERSION (exported from the package, carried on the ready event, and available as window.ConnectlyWebchat.version on the script-tag path) identifies the widget code. It is the first thing Connectly support will ask for. The npm package carries its own version, on its own schedule; the two are not expected to match.

Get Started

Campaigns

Messaging

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Webchat

Resources

`window.ConnectlyWebchat` — script tag only

`<connectly-webchat>` — both integrations

Opening and closing the panel

Events

Version

​window.ConnectlyWebchat — script tag only

​<connectly-webchat> — both integrations

​Opening and closing the panel

​Events

​Version

`window.ConnectlyWebchat` — script tag only

`<connectly-webchat>` — both integrations

Opening and closing the panel

Events

Version