Live Chat SDK

SDK events

The widget dispatches a small set of CustomEvents on window. Listen for them with window.addEventListener — data lives on event.detail.

hellouone:ready

window.addEventListener('hellouone:ready', handler)

Fires once the iframe has loaded and window.$hellouOne is fully populated. Use it as the gate for any boot-time calls — setting the user, opening the panel, registering custom attributes.

Detail

event.detail is null. The signal itself is the payload.

Example

window.addEventListener('hellouone:ready', () => {
  window.$hellouOne.setUser('42', {
    name: 'Ada Lovelace',
    email: '[email protected]',
    identifier_hash: identifierHash
  });
});

hellouone:on-message

window.addEventListener('hellouone:on-message', handler)

Fires every time a message is created or updated in the active conversation — both outgoing visitor messages and incoming agent messages. The full message record is passed in event.detail.

Detail shape

`id`	Numeric message ID.
`conversation_id`	ID of the conversation this message belongs to.
`content`	The message body as a string.
`content_type`	Usually `'text'`; other values cover input cards and forms.
`content_attributes`	Extra structured data — e.g. `{ deleted: true }` when a message is removed.
`message_type`	`0` for outgoing agent messages, `1` for incoming visitor messages.
`sender_type`	`'Agent'` or `'User'`.
`created_at`	Unix timestamp (seconds).
`attachments`	Array of attachments; each entry includes `data_url`, `file_type`, `extension`.

Example

window.addEventListener('hellouone:on-message', (event) => {
  const message = event.detail;
  if (message.sender_type === 'Agent') {
    analytics.track('support_message_received', {
      conversationId: message.conversation_id,
      length: message.content.length
    });
  }
});

Fires on updates too

This event also dispatches when an existing message is edited or marked deleted. If you’re feeding it into analytics, dedupe by id.

hellouone:error

window.addEventListener('hellouone:error', handler)

Fires when an SDK call fails server-side. The most common case is a rejected setUser when identity validation is mandatory and the hash doesn’t match.

Detail shape

event.detail carries the error returned by the server. The exact shape depends on the failure, but expect at least an error string. For setUser failures it surfaces as 'SET_USER_ERROR'.

Example

window.addEventListener('hellouone:error', (event) => {
  console.warn('HellouOne error', event.detail);
});

Listening from the parent page

The events fire on the top-level window, not on the widget iframe. You don’t need postMessage plumbing — addEventListener on the page you embedded the snippet on is enough.