SDK Reference

The SDK is the global object window.$chatty. This page lists everything it exposes.

Methods

on and off are also available as push verbs — push(['on', event, cb]) is equivalent to on(event, cb).

Commands pushed before the widget bundle loads are buffered and replayed in order once it is ready, so you never need to poll for readiness.

window.$chatty = window.$chatty || [];
window.$chatty.push(['do', 'chat:open'])

do actions

Run with push(['do', action, ...args]).

Widget visibility

window.$chatty.push(['do', 'chat:open'])
window.$chatty.push(['do', 'launcher:hide'])

Messaging

window.$chatty.push(['do', 'message:send', 'text', 'I need help with my order'])
window.$chatty.push(['do', 'typing:set', true])

The first argument of message:send is the message type and must be 'text'. The SDK cannot send attachments or rich content.

If a required pre-chat form is on screen, message:send is held and delivered as the first message as soon as the form is submitted.

Identity and session

window.$chatty.push(['do', 'identify', {
  email: 'jane@example.com',
  name: 'Jane Doe',
  phone: '+15550134',
  attributes: { plan: 'gold' }
}])

identify is a shortcut for the matching set user:* actions. Both merge into the same visitor record, so use whichever fits your code — identify for a single call at page load, set when values arrive at different times.

Conversation control

window.$chatty.push(['do', 'escalate'])
window.$chatty.push(['do', 'article:show', articleId])

Pre-chat form

Available from SDK 1.1.0.

if (window.$chatty.is('prechat:visible') && !window.$chatty.is('prechat:required')) {
  window.$chatty.push(['do', 'prechat:skip'])
}

Prefill the fields with set prechat:field before calling prechat:submit.

Custom event tracking

window.$chatty.push(['do', 'event:track', 'viewed_size_guide', { product: 'shirt-101' }])

Every tracked event is also re-dispatched on the page as a DOM CustomEvent named chatty:event, so other scripts can consume it without touching the SDK:

document.addEventListener('chatty:event', (e) => {
  console.log(e.detail.name, e.detail.data)  // 'viewed_size_guide', { product: 'shirt-101' }
})

set actions

Run with push(['set', action, value]).

Composer and visitor data

window.$chatty.push(['set', 'message:text', 'I want to know about shipping'])
window.$chatty.push(['set', 'user:email', 'jane@example.com'])
window.$chatty.push(['set', 'user:context', { vipLevel: 3, accountAge: '2 years' }])

user:context and shop:data merge rather than replace, so you can add keys as the page learns more. Values must be a string, number, or boolean.

Commerce context

Give the AI assistant structured context about what the visitor is looking at.

window.$chatty.push(['set', 'product', { id: 123, title: 'Steel Door', price: '499.00' }])
window.$chatty.push(['set', 'cart', { items: 2, total: '648.00' }])
window.$chatty.push(['set', 'order', { name: '#1042', status: 'shipped' }])

Read the merged result back with $chatty.get('commerce:context').

Locale

window.$chatty.push(['set', 'locale', 'de'])

Pre-chat prefill

Available from SDK 1.1.0. Takes a field name and a value, so this is the one set action with two arguments.

window.$chatty.push(['set', 'prechat:field', 'name', 'Jane Doe'])
window.$chatty.push(['set', 'prechat:field', 'email', 'jane@example.com'])
window.$chatty.push(['set', 'prechat:field', 'phone', '+15550134'])
 
// 'message' is queued and sent automatically once the form is submitted
window.$chatty.push(['set', 'prechat:field', 'message', 'Where is my order #1042?'])

Prefills are sticky — they apply even if the form appears later in the session.

Events

Subscribe with on(event, callback). The callback receives one data object, or nothing where the payload column shows —.

Lifecycle

Messages

Conversation

Pre-chat and lead capture

Presence and typing

Avoiding duplicate handling

ai:reply and human:reply cover the same replies that message:received reports, split by sender. Subscribe to either message:received or the ai:reply / human:reply pair — not both — or a single reply runs your handler twice. This matters most for analytics, where it doubles your counts.

// Either this — one handler, branch on the payload
window.$chatty.on('message:received', ({ isAdmin }) => { /* ... */ })
 
// Or this — two handlers, no branching. Not both.
window.$chatty.on('ai:reply', () => { /* ... */ })
window.$chatty.on('human:reply', () => { /* ... */ })

Unsubscribing

Pass the same function reference you subscribed with. Anonymous inline functions cannot be removed.

function onOpen() { /* ... */ }
 
window.$chatty.on('chat:opened', onOpen)
window.$chatty.off('chat:opened', onOpen)

States

Read synchronously with is(key) → boolean.

if (window.$chatty.is('chat:opened')) {
  window.$chatty.push(['do', 'chat:close'])
}

Values

Read synchronously with get(key).

const unread = window.$chatty.get('chat:unread:count')

Limits and validation

The SDK enforces limits to keep the widget responsive and to prevent abuse.

Error handling

Commands never throw. A command that fails validation or hits a rate limit is dropped, and the SDK logs a warning prefixed with [ChattySDK] to the browser console.

window.$chatty.push(['set', 'user:email', 'not-an-email'])
// [ChattySDK] ... — the command is ignored, execution continues

Two consequences worth designing around:

• There is no error callback and no return value. Your code cannot detect a rejected command at runtime, so validate input on your side before pushing it — especially anything coming from a form or a URL parameter.
• A dropped command is silent to the visitor. If a rate limit swallows a message:send, nothing appears in the chat. Throttle on your side rather than relying on the SDK to queue.

Security and trust boundary

The SDK runs entirely in the visitor's browser. Everything below follows from that.

Identity is not verified. identify and the set user:* actions take whatever the page gives them. Anyone can open the browser console and pass another person's email. Chatty uses these values to label the conversation for your team, so:

• Do not use SDK identity to unlock account data, order details, or anything else you would gate behind a login.
• Do not treat a matching email in your inbox as proof of identity.

Input is sanitised. All text is sanitised before it reaches the widget. HTML and script content is rejected, and the fields marked "no HTML" above reject markup outright.

Only documented keys are exposed. is and get return the keys listed on this page. The SDK object does not expose the widget's internal state, and its methods are frozen so ordinary scripts on the page cannot replace them by accident. This is a guard against collisions with other scripts, not a defence against a hostile script — any script on your storefront runs with the same privileges as your own code.

Anything you push is visible to the visitor. user:context, shop:data, and the commerce objects sit in page memory. Pass what your support team needs to help, and nothing more — no internal costs, margins, risk scores, or notes you would not show the customer.

Analytics and GA4

Send Chatty activity to Google Analytics 4. Add this after your GA4 snippet, for example in theme.liquid.

<script>
  window.$chatty = window.$chatty || [];
 
  window.$chatty.push(['on', 'sdk:ready', function () {
    // Chat window opened
    window.$chatty.on('chat:opened', function () {
      gtag('event', 'chatty_chat_opened');
    });
 
    // First message submitted — a new conversation exists
    window.$chatty.on('conversation:started', function (data) {
      gtag('event', 'chatty_conversation_started', {
        conversation_id: data.conversationId
      });
    });
 
    // Every message the visitor sends
    window.$chatty.on('message:sent', function () {
      gtag('event', 'chatty_message_sent');
    });
 
    // Pre-chat form submitted
    window.$chatty.on('prechat:submitted', function (data) {
      gtag('event', 'chatty_lead_submitted', {
        conversation_id: data.conversationId
      });
    });
 
    // Email captured in the pre-chat form
    window.$chatty.on('email:captured', function () {
      gtag('event', 'chatty_email_captured');
    });
  }]);
</script>

Then mark one of them as a conversion in the GA4 admin.

Migrating from another chat widget? The usual callbacks map like this:

Recipes

Custom "Chat with us" button

<button onclick="window.$chatty.push(['do', 'chat:open'])">Chat with us</button>

Open chat with a question already typed

<button onclick="
  window.$chatty.push(['do', 'chat:open']);
  window.$chatty.push(['set', 'message:text', 'What is your returns policy?']);
">Ask about returns</button>

One-click support with the message already sent

<button onclick="
  window.$chatty.push(['do', 'chat:open']);
  window.$chatty.push(['do', 'message:send', 'text', 'I need help with my recent order']);
">Get order help</button>

Hide the widget on specific pages

if (window.location.pathname.startsWith('/pages/legal')) {
  window.$chatty.push(['do', 'chat:hide'])
}

Identify logged-in customers (Shopify Liquid)

{% if customer %}
<script>
  window.$chatty = window.$chatty || [];
  window.$chatty.push(['do', 'identify', {
    email: {{ customer.email | json }},
    name: {{ customer.name | json }}
  }]);
</script>
{% endif %}

Hold the widget until the visitor accepts cookies

Useful where consent is required before loading third-party chat.

window.$chatty = window.$chatty || [];
window.$chatty.push(['do', 'chat:hide'])
 
// Call this from your consent banner's "accept" handler
function onConsentGiven() {
  window.$chatty.push(['do', 'chat:show'])
}

What the SDK cannot do

• Read past conversations or message history — there is no getter for it.
• Send attachments, images, or rich content. message:send is text only.
• Reply as an agent, or act on behalf of your team.
• Embed the widget. The SDK controls a widget that Chatty already loaded; it is not an npm package.

For server-side access to conversations, see the Chat Conversations API.

Browser support

Chrome 60+, Firefox 55+, Safari 12+, Edge 79+. The SDK uses ES6 and does not ship a transpiled fallback for older browsers.

Changelog

Check the version at runtime before calling a newer API:

window.$chatty.on('sdk:ready', () => {
  const [major, minor] = window.$chatty.version.split('.').map(Number)
 
  if (major > 1 || (major === 1 && minor >= 1)) {
    window.$chatty.push(['set', 'prechat:field', 'email', 'jane@example.com'])
  }
})

Compare the parts as numbers, not the whole string — '1.9.0' >= '1.10.0' is true in a string comparison and wrong.

Troubleshooting

window.$chatty is undefined. The widget script has not loaded on that page. Check that the Chatty app embed is enabled in your theme and that the page is not excluded. Starting your code with window.$chatty = window.$chatty || [] makes it safe regardless of load order.

chat:open does nothing. The widget may still be initialising — wait for sdk:ready — or it was hidden earlier by chat:hide, in which case call chat:show first.

message:send seems ignored. Check the console for a [ChattySDK] rate-limit or validation warning. If a required pre-chat form is open, the message is held and sent once the form is submitted.

A handler runs twice. You are probably subscribed to message:received and to ai:reply or human:reply at the same time. See Avoiding duplicate handling.

Events are not reaching GA4. Register listeners inside or after sdk:ready, and confirm the event fires at all from the console first:

window.$chatty.on('chat:opened', () => console.log('opened'))

Need help?

If a command still is not working, confirm the widget is loading on the page — window.$chatty should be defined. Still stuck? Contact the Chatty support team from your dashboard.