> ## 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.

# Chat widget SDK

> Drive the chat widget from JavaScript with window.twSdk: update variables, open the chat, and start a new conversation

After the chat widget loads, it exposes a small JavaScript API on
`window.twSdk`. Use it to update variables during a conversation, open the
widget, or start a fresh conversation from your own buttons and page logic.

The widget initializes itself from `window.twConfig`, so you don't call an init
function. See [Installation](/documentation/behavior/chat#installation) to load
the script. Wait until `window.twSdk` exists before you call it.

## Update variables

`setVariables` pushes context variables into the visitor's live conversation
without a reload. Reach for 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
});
```

The argument mirrors the `variables` and `signedVariables` you set in
`window.twConfig` at install time. Pass either field, or both. The call returns
nothing and sends the update in the background.

| Field             | Type                                 | Trust                                                                                                                                                 |
| :---------------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variables`       | object of string, number, or boolean | Unsigned. The visitor's browser can change these, so Typewise keeps them unverified.                                                                  |
| `signedVariables` | JWT string                           | Verified. Your backend signs it, so Typewise trusts the claims inside. See [Chat identity verification](/guides/channels/chat-identity-verification). |

### What persists

<Note>
  Typewise keeps only the variables you declare in
  [Context Variables](/documentation/settings/context-variables). It drops any
  name you haven't declared, and the call still succeeds. Declare every variable
  you send.
</Note>

Three rules decide the result:

* **Declared only.** Typewise drops undeclared names at ingest. A name like
  `order_number` persists only when it's declared for the workspace.
* **Active conversation only.** The update lands on the conversation the visitor
  has open. When no conversation is active (before the first message, or after
  the current one closes), Typewise holds the values and applies them to the
  next conversation the visitor starts. It doesn't change a conversation that
  already closed.
* **Signed beats unsigned.** An unsigned value can't overwrite one that arrived
  verified. This stops a visitor from editing a value your backend already
  signed.

### Rotate trusted values after login

A page often starts anonymous, the visitor signs in, and you then raise their
identity to a verified value. Sign a new token on your backend and pass it:

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

## Open the chat

Open the widget from your own element:

```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();
```

## Call the SDK safely

`window.twSdk` exists only after the widget script loads. Guard your calls so an
early one doesn't throw:

```javascript theme={null}
if (window.twSdk) {
  window.twSdk.setVariables({ variables: { locale: "en-US" } });
}
```

## See also

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