Storefront SDK

ⓘ

Who can use this feature?

Available to all users on any plan.
Requires a developer to add JavaScript to your storefront theme.

Overview

The Chatty Storefront SDK is a small JavaScript API for controlling the Chatty chat widget from your store's pages. With it you can open or close the chatbox, prefill or send a message, pass customer and shop context, track custom events, and react to what the visitor is doing in chat.

It's the right tool when you want the widget to respond to your own buttons, flows, or page logic — for example, opening chat from a "Need help?" link, or pre-filling a message from a product page.

How it works

The SDK is exposed on the page as window.$chatty. It uses a buffered command queue: you push commands as [verb, action, ...args] tuples, and they run as soon as the widget is ready — so you can call it even before the widget has finished loading.

// Open the chatbox
window.$chatty.push(['do', 'chat:open'])

The four verbs are:

Verb	What it does
`do`	Perform an action (open, close, send…).
`set`	Set a value (prefill text, customer context…).
`on`	Subscribe to an event.
`off`	Unsubscribe from an event.

Install

The SDK ships with the Chatty widget — once Chatty is installed on your store, window.$chatty is available automatically. There's nothing extra to install.

If you want to queue commands before the widget bundle finishes loading, add this bootstrap snippet near the top of your theme (optional but recommended):

<script>
  window.$chatty = window.$chatty || [];
</script>

Any commands you push before the widget loads are buffered and replayed in order once it's ready.

The SDK controls a widget that's already on the page. It is not an npm package and does not embed Chatty by itself — install the Chatty app first so the widget loads on your storefront.

Quick start

Open the chatbox from a button

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

Prefill and send a message

// Prefill the input without sending
window.$chatty.push(['set', 'message:text', 'I have a question about my order'])
 
// Or send it immediately
window.$chatty.push(['do', 'message:send', 'text', 'Is the Daris Tee back in stock?'])

Pass who the customer is

window.$chatty.push(['set', 'user:email', '[email protected]'])
window.$chatty.push(['set', 'user:context', { plan: 'vip', orders: 4 }])

React when a reply arrives

window.$chatty.on('message:received', (data) => {
  console.log('Agent replied:', data.text)
})

See the full SDK Reference for every method, action, event, and limit.

Webhooks SDK Reference