SDK Events

The SDK emits 22 events. Subscribe with on(event, callback), unsubscribe with off(event, callback).

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

An event name the SDK does not know is rejected: the callback is never registered and a [ChattySDK] warning goes to the console. Nothing is thrown.

How to read the payload column

Each callback receives one argument. Where the payload column says None, the callback is called with no argument at all, so do not destructure it.

Errors thrown inside your callback are caught and logged. One broken handler does not stop the other handlers or the widget.

Lifecycle

sdk:ready means commands are accepted. It does not mean the chat window has rendered. See When your commands run.

Messages

Payload fields:

• text — the message body as plain text.
• type — always 'text'. The SDK has no other message type.
• isAutomated — true for an AI reply, false for a human agent. This is the field to branch on.
• isAdmin — always true on message:received, because the event only covers replies coming into the widget. It does not tell you whether a human or the AI wrote the reply.
• id — the removed message ID.

Conversation

memberId is the ID of the agent who picked the conversation up. handoff needs both conditions: the conversation must leave AI mode and have an assigned agent. A conversation that leaves AI mode without an assignment emits nothing.

Pre-chat and lead capture

Two limits worth designing around:

• Skipping does not count as submitting. do prechat:skip, and the visitor choosing to chat anonymously, emit neither prechat:submitted nor email:captured.
• conversationId can be null on prechat:submitted when the conversation record is not ready yet. Guard before you send it anywhere.
• email:captured only covers the pre-chat form. An email the visitor types into the chat, or one you pass with set user:email, does not emit it.

Presence and typing

agent:available and agent:unavailable are two sides of one signal, so exactly one of them fires per change. To track chat hours, subscribe to both. The current value is also readable at any time with $chatty.is('agent:online').

Order at startup

Only one thing is guaranteed about ordering: sdk:ready comes first, and any command you pushed before the widget loaded has already run by the time it fires.

Everything after that depends on how the widget is configured and what the visitor does:

1. sdk:ready — commands are accepted.
2. agent:available or agent:unavailable — once chat hours have been evaluated.
3. prechat:shown — if a pre-chat form is configured and the visitor opens the chat.
4. chat:opened — when the window opens.
5. prechat:submitted, and email:captured with it — if the visitor completes the form.
6. conversation:started — when the first message goes through.

Do not write code that depends on step 2 arriving before step 4, or on conversation:started arriving before a reply. Treat each event as independent.

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. Otherwise 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', ({ isAutomated }) => { /* ... */ })
 
// Or this: two handlers, no branching. Not both.
window.$chatty.on('ai:reply', () => { /* ... */ })
window.$chatty.on('human:reply', () => { /* ... */ })

The same trap applies to prechat:submitted and email:captured, which fire together for one submission, and to prechat:submitted and conversation:started, which both fire for one visitor on a shop with a required pre-chat form.

Unsubscribing

off(event, callback) removes one handler. Pass the same function reference you subscribed with. An anonymous inline function cannot be removed, because you no longer hold a reference to it.

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

Calling off with the event name only removes every handler registered for that event, including handlers registered by other scripts on the page. Use it deliberately.

window.$chatty.off('chat:opened')  // removes all chat:opened handlers

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.

Note the shape of the snippet above: it registers listeners inside on('sdk:ready', …), and it reaches the SDK through push. Before the widget bundle loads, window.$chatty is a plain array, so push is the only method that exists. See When your commands run.

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

Custom events you raise yourself

do event:track feeds a named event into the widget context, and the widget re-dispatches it on the page as a DOM CustomEvent named chatty:event. That is a browser event, not an SDK event, so you listen for it on window, not with $chatty.on.

window.$chatty.push(['do', 'event:track', 'viewed_size_guide', { product: 'shirt-101' }])
 
window.addEventListener('chatty:event', (e) => {
  console.log(e.detail.name, e.detail.data)  // 'viewed_size_guide', { product: 'shirt-101' }
})

The re-dispatch happens only once the chat window has rendered. See event:track for the size limits on name and data.

Need help?

If an event never reaches your handler, confirm the widget is loading on the page and that you registered the listener inside or after sdk:ready. Check the console for a [ChattySDK] Unknown event warning, which means the event name is misspelt. Still stuck? Contact the Chatty support team from your dashboard.