> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Drive the widget from your own code with the ConnectlyWebchat page global, the custom element and the events it dispatches 🎛️

<Accordion title="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](https://webchat.connectly.ai/docs/).
</Accordion>

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.

```ts theme={null}
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](/webchat/configure#attributes) for the attribute list.

```js theme={null}
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.

```tsx theme={null}
// 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:

```js theme={null}
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.