# Host API

Drive the widget from your own JavaScript. Commands, events, and identity.

Source: https://docs.omazy.ai/widget/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.

```js
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. |

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

:::note[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.

```js
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.