SDK Reference

ⓘ

Who can use this feature?

Available to all users on any plan.
New to the SDK? Start with the SDK overview.

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

Methods

Method	Returns	Description
`push([verb, action, ...args])`	—	Run a command. Verbs: `do`, `set`, `on`, `off`.
`on(event, callback)`	—	Subscribe to an event.
`off(event, callback)`	—	Unsubscribe. Pass the same function reference used in `on`.
`is(key)`	`boolean`	Synchronously read a boolean state (see States).
`get(key)`	`value`	Synchronously read a value (see Values).
`version`	`string`	SDK version, e.g. `'1.0.0'`.

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

`do` actions

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

Action	Arguments	Description
`chat:open`	—	Open the chatbox.
`chat:close`	—	Close the chatbox.
`chat:show`	—	Show the widget launcher.
`chat:hide`	—	Hide the widget launcher.
`message:send`	`'text', content`	Send a message as the visitor.
`event:track`	`name, data?`	Track a custom event.
`session:reset`	—	Reset the current chat session.

window.$chatty.push(['do', 'message:send', 'text', 'Hello!'])
window.$chatty.push(['do', 'event:track', 'viewed_pricing', { plan: 'pro' }])

`set` actions

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

Action	Value	Description
`message:text`	`string`	Prefill the input box (without sending).
`user:email`	`string`	Set the visitor's email.
`user:context`	`object`	Merge custom data about the visitor.
`shop:data`	`object`	Merge custom data about the shop/page context.

window.$chatty.push(['set', 'message:text', 'I need a refund'])
window.$chatty.push(['set', 'user:context', { vip: true, lifetimeOrders: 12 }])

Events

Subscribe with on(event, callback).

Event	Payload	Fires when…
`sdk:ready`	—	The SDK has loaded and is ready.
`chat:opened`	—	The chatbox opens.
`chat:closed`	—	The chatbox closes.
`message:sent`	`{ text, type }`	The visitor sends a message.
`message:received`	`{ text, isAdmin }`	A reply arrives (agent or AI).

window.$chatty.on('sdk:ready', () => {
  console.log('Chatty is ready')
})
 
window.$chatty.on('message:received', ({ text, isAdmin }) => {
  if (isAdmin) console.log('Reply:', text)
})

ⓘ

To remove a listener with off, keep a reference to the same function you passed to on. Anonymous inline functions can't be removed.

States

Read synchronously with is(key) → boolean.

Key	True when…
`chat:opened`	The chatbox is open.
`chat:closed`	The chatbox is closed.
`chat:visible`	The launcher is visible.
`session:ongoing`	There's an active chat session.

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

Values

Read synchronously with get(key).

Key	Returns
`message:text`	Current text in the input box.
`session:identifier`	The current session ID.
`chat:unread:count`	Number of unread messages.

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

Limits

To keep the widget responsive and prevent abuse, the SDK enforces a few limits:

Action	Limit
`message:send`	Up to 15/min, at least 1 second apart, max 5,000 characters.
`event:track`	Event name ≤ 200 chars; data ≤ 20 keys / 1,000 chars.
`user:email`	Must be a valid email, ≤ 254 chars.
`user:context`	≤ 50 keys; each value ≤ 2,000 chars (string, number, or boolean).

All text inputs are sanitized — <script>, <iframe>, javascript: URLs, and inline on*= handlers are stripped.

Full example

<button id="help-btn">Need help?</button>
 
<script>
  window.$chatty = window.$chatty || [];
 
  // Identify the visitor
  window.$chatty.push(['set', 'user:email', '[email protected]'])
  window.$chatty.push(['set', 'user:context', { plan: 'vip' }])
 
  // Open chat from a custom button with a prefilled message
  document.getElementById('help-btn').addEventListener('click', () => {
    window.$chatty.push(['set', 'message:text', 'I have a question about my order'])
    window.$chatty.push(['do', 'chat:open'])
  })
 
  // Log replies
  window.$chatty.on('message:received', ({ text, isAdmin }) => {
    console.log(isAdmin ? 'Agent: ' : 'AI: ', text)
  })
</script>

Need help?

If a command isn't working, confirm the Chatty widget is installed and loading on the page (window.$chatty should be defined). Still stuck? Contact the Chatty support team from your dashboard.

Overview Product Roadmap