Control the chat widget with JavaScript

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.

Want to render the conversation in your own UI instead of the bubble? Use the Chat SDK.

Prerequisites

The chat widget is installed on your page. See Installation.
Every variable you send is declared in Context Variables.

Available functions

setVariables

Send context to the visitor’s conversation

openChat

Open the widget from your own button

startNewConversation

Close the current conversation and start fresh

The widget initializes itself from window.twConfig, so there is no init function to call. 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:

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.

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.

object

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

string

A JWT your backend signs. Verified, so values pass the Trusted only check. See Identity verification.

Which values are kept

Declared variables only. Typewise drops any name you haven’t declared in Context Variables. 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.

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

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:

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

Start a new conversation

Close the current conversation and start a fresh one:

window.twSdk?.startNewConversation();

Identity verification: sign variables so they arrive verified
Context Variables: declare the variables Typewise keeps
Chat configuration: install and configure the widget

Migrate to Typewise

Channels

Integrations

Best practices

Control the chat widget with JavaScript

Prerequisites

Available functions

setVariables

openChat

startNewConversation

Wait for the widget to load

Update variables

Which values are kept

Open the chat

Start a new conversation

​Prerequisites

​Available functions

setVariables

openChat

startNewConversation

​Wait for the widget to load

​Update variables

​Which values are kept

​Verify the visitor after login

​Open the chat

​Start a new conversation

​Related

Prerequisites

Available functions

Wait for the widget to load

Update variables

Which values are kept

Verify the visitor after login

Open the chat

Start a new conversation

Related