Widget JavaScript API

Once the widget loads, it exposes window.chatisto. Use it to open the chat from your own buttons and to tell Chatisto who the visitor is.

Wait until the widget is ready

LoadChatisto() returns a promise that resolves once the widget is on the page. Put your calls there:

window.chatistoLoader
    .LoadChatisto({ publicKey: 'YOUR_PUBLIC_KEY' })
    .then(() => {
        window.chatisto.setProperty([{ key: 'email', value: 'jane@example.com' }]);
    });

The chat inside the widget may still be connecting at that moment. window.chatisto.widgetReady() returns true once it's fully started. setProperty() waits for this on its own, so you don't need to check.

Open the chat from your own button

<button onclick="window.chatisto.visual.open()">Chat with us</button>

Identify logged-in users

By default every visitor is anonymous. If your visitors are logged in, pass what you know about them. Operators see it in the conversation sidebar and the contact profile, and it stays attached to the contact.

window.chatisto.createCustomer({
    email: 'jane@example.com',
    name: 'Jane Cooper',
    plan: 'Pro',
    user_id: '48213'
});

• Pass a plain object of key: value pairs. Each key you send becomes a contact field automatically.
• Calling createCustomer() starts a new conversation for the visitor, so call it once after login. Don't call it on every page load.
• It returns a promise that resolves with the visitor's identity (customer and chatroom IDs).

Never send passwords, payment details or other secrets. Anything you send is visible to your operators.

Update contact properties

setProperty() updates fields that already exist on the contact, for example a field collected by a scenario form:

window.chatisto.setProperty([
    { key: 'email', value: 'jane@example.com' },
    { key: 'newsletter-form.company', value: 'Acme Inc.' }
]);

• key is the field key. To target a field in one specific form, use form-name.field-key.
• value must be a string. Validation rules set on the field are applied, so an invalid email is rejected.
• If you call it before the widget is ready, the call is queued and sent once the widget starts (it returns 'queued').
• The response lists each key with success: true/false and a reason, so you can see which fields didn't match.

Start a fresh conversation

A returning visitor continues their previous conversation if it was opened less than an hour ago. To force a clean start, for example after a user logs out:

await window.chatisto.refreshIdentityAndRestartChat();

Reset the widget completely

For single-page apps that need to tear the widget down and load it again (for example, to switch to a different integration):

window.chatistoLoader.resetChatisto();
window.chatistoLoader.LoadChatisto({ publicKey: 'OTHER_PUBLIC_KEY' });

Including the SDK script twice, or calling LoadChatisto() twice, is harmless. Chatisto keeps a single widget instance and logs a warning in the console.

Buttons inside AI and scenario messages

Messages can contain clickable quick-reply buttons with this syntax:

[BUTTON:Track my order|track_order|I need to track my order]

The three parts are: the button label, an action name for your own tracking, and the message that is sent for the visitor when they click it. You can use it in scenario messages and in AI agent instructions or skills.