Chat widget SDK

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

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.

What persists

Typewise keeps only the variables you declare in Context Variables. It drops any name you haven’t declared, and the call still succeeds. Declare every variable you send.

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.

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:

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:

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

Call the SDK safely

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

if (window.twSdk) {
  window.twSdk.setVariables({ variables: { locale: "en-US" } });
}

Migrate to Typewise

Channels

Integrations

Best practices

Update variables

What persists

Open the chat

Start a new conversation

Call the SDK safely

See also

​Update variables

​What persists

​Rotate trusted values after login

​Open the chat

​Start a new conversation

​Call the SDK safely

​See also

Update variables

What persists

Rotate trusted values after login

Open the chat

Start a new conversation

Call the SDK safely

See also