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, hand the conversation to a human, prefill the pre-chat form, 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.

The current SDK version is 1.1.0. Read it at runtime with window.$chatty.version.

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', 'shopper@example.com'])
window.$chatty.push(['set', 'user:context', { plan: 'vip', orders: 4 }])

Fill in the pre-chat form ahead of time

// Sticky — applied even if the form appears later
window.$chatty.push(['set', 'prechat:field', 'name', 'Jane Doe'])
window.$chatty.push(['set', 'prechat:field', 'email', 'shopper@example.com'])

React when a reply arrives

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

Before you ship

Customer details you pass from the browser are supplied by the page, not verified by Chatty — anyone can open the console and send a different email. Use them to give your support team context, never to unlock account or order data. See Security and trust boundary before you wire identify into your theme.

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

Webhooks SDK Reference