Host API

Everything the widget can be told to do goes through one function. If you have ever used an analytics snippet, the shape will feel familiar: a single global that takes a command name and some arguments.

ouWidget('open')
ouWidget('identify', { id: 'cus_123', name: 'Ada', email: 'ada@example.com' })

Commands

Command	Arguments	What it does
init	config object	Mounts the widget. Called once by the install snippet.
open	none	Opens the panel.
close	none	Closes it.
toggle	none	Opens if closed, closes if open.
show	none	Shows the launcher.
hide	none	Hides the launcher without unmounting.
identify	identity object	Tells the widget who this visitor is. login is an alias.
logout	none	Forgets them. Call this on sign-out.
setContext	context object	Attaches page or account context to the next conversation.
startChat	optional message	Opens and begins a conversation.
sendMessage	message	Sends on the visitor’s behalf.
on	event, handler	Subscribes to an event.
off	event, handler	Unsubscribes.
getState	callback	Calls back with a state snapshot.
getUnread	callback	Calls back with the unread count.
destroy	none	Unmounts and removes listeners.

hide and destroy are not the same thing, and the difference matters. hide keeps the widget alive with the lights off, so unread counts keep arriving. destroy packs up and leaves. Reach for hide on a checkout page and destroy on sign-out.

Events

Subscribe with on, or listen for a DOM CustomEvent named ouchat:widget:<event> if you would rather not hold a reference.

Event	Fires when
ready	The widget has mounted and is usable.
open	The panel opened.
close	The panel closed.
message	A message arrived.
unread	The unread count changed.
conversation-started	A new conversation began.
identity-changed	identify or logout took effect.

ouWidget('on', 'unread', function (count) {
  document.title = count ? '(' + count + ') Support' : 'Support'
})

Two event prefixes, one meaning

Events are dispatched under both ouchat: and the older omazy: prefix while existing installs migrate. Listen for ouchat:. The omazy: twin is there so nothing that already works stops working, which is the only good reason to keep two names for one thing.

Identity

identify is what turns an anonymous visitor into someone your agent recognises. Until you call it, the widget treats a person as a stranger, which is correct but not especially useful once they have signed in to your app.

ouWidget('identify', {
  id: 'cus_123',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
})

Call logout when they sign out. A shared machine with a remembered identity is a support ticket waiting to be written, and it will be written by the wrong person.