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

# Control the chat widget with JavaScript

> Use window.twSdk to update variables, open the chat, and start a new conversation from your own page logic

Once the chat widget loads, it exposes a small JavaScript API on `window.twSdk`.
Use it to react to what happens on your page: update context when the visitor
signs in, open the chat from your own button, or start over.

> [!TIP]
>
> Want to render the conversation in your own UI instead of the bubble? Use the
> [Chat SDK](https://docs.typewise.app/guides/channels/chat-sdk/overview.md).

## Prerequisites

* The chat widget is installed on your page. See
  [Installation](https://docs.typewise.app/documentation/behavior/chat.md#installation).
* Every variable you send is declared in
  [Context Variables](https://docs.typewise.app/documentation/settings/context-variables.md).

## Available functions

> **[setVariables](#update-variables)**
>
> Send context to the visitor's conversation

> **[openChat](#open-the-chat)**
>
> Open the widget from your own button

> **[startNewConversation](#start-a-new-conversation)**
>
> Close the current conversation and start fresh

The widget initializes itself from `window.twConfig`, so there is no `init`
function to call.

## Wait for the widget to load

`window.twSdk` exists only after the widget has loaded and fetched its
configuration. The widget fires no ready event, so to run a call that must not
be lost, wait until `window.twSdk` exists:

```javascript theme={null}
function withTwSdk(callback, attempts = 300) {
  if (window.twSdk) return callback(window.twSdk);
  if (attempts > 0) setTimeout(() => withTwSdk(callback, attempts - 1), 100);
}

withTwSdk((twSdk) => {
  twSdk.setVariables({ variables: { locale: "en-US" } });
});
```

The helper checks every 100 ms and gives up after 30 seconds, for example when
the widget can't load on this domain. For calls a visitor triggers, such as
opening the chat from a button, `window.twSdk?.` is enough.

## Update variables

`setVariables` sends new context to the visitor's conversation without a page
reload. Use it when data changes after the chat loads: the visitor signs in,
adds items to a cart, or opens a different order.

```javascript theme={null}
window.twSdk.setVariables({
  variables: {
    order_number: "A12938",
    cart_size: 3,
  },
  signedVariables: "<fresh JWT from your backend>", // optional
});
```

Pass `variables`, `signedVariables`, or both. They work like the fields of the
same name in `window.twConfig`. The call returns nothing and sends the update in
the background.

**variables** `object`

Strings, numbers, or booleans. Unverified, because the visitor's browser can
change them.

**signedVariables** `string`

A JWT your backend signs. Verified, so values pass the **Trusted only** check.
See [Identity
verification](https://docs.typewise.app/guides/channels/chat-widget/identity-verification.md).

### Which values are kept

* **Declared variables only.** Typewise drops any name you haven't declared in
  [Context Variables](https://docs.typewise.app/documentation/settings/context-variables.md). The call still
  succeeds, so a typo fails silently.
* **The open conversation.** The update applies to the conversation the visitor
  has open. With no open conversation (before the first message, or after one
  closes), Typewise holds the values for the next conversation. A closed
  conversation is never changed.
* **Signed values win.** An unsigned value can't overwrite a value that arrived
  signed, so a visitor can't edit what your backend verified.

### Verify the visitor after login

A page often starts anonymous and the visitor signs in later. Fetch a new token
from your backend and pass it:

```javascript theme={null}
async function onLogin(userId) {
  const signedVariables = await fetchSignedVariables(userId); // your backend
  withTwSdk((twSdk) => twSdk.setVariables({ signedVariables }));
}
```

## Open the chat

Open the widget from any element on your page:

```javascript theme={null}
document.querySelector("#help-button").addEventListener("click", () => {
  window.twSdk?.openChat();
});
```

## Start a new conversation

Close the current conversation and start a fresh one:

```javascript theme={null}
window.twSdk?.startNewConversation();
```

## Related

* [Identity verification](https://docs.typewise.app/guides/channels/chat-widget/identity-verification.md):
  sign variables so they arrive verified
* [Context Variables](https://docs.typewise.app/documentation/settings/context-variables.md): declare the
  variables Typewise keeps
* [Chat configuration](https://docs.typewise.app/documentation/behavior/chat.md): install and configure the
  widget


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.