Live Chat SDK

SDK methods

Once the widget has booted, every runtime method hangs off the window.$hellouOne object. None of these are available before the hellouone:ready event fires — wait for it before calling anything below.

Wait for ready

Wrap any boot-time calls in a hellouone:ready listener. The widget runs inside an iframe, so the global doesn’t exist the instant your snippet is parsed.

Opening & visibility

toggle()

$hellouOne.toggle(state?: 'open' | 'close')

Opens or closes the chat panel. With no argument, the current state is flipped. Pass 'open' or 'close' to force a state regardless of where the panel is now.

Example

// Open the chat in response to your own button
document.querySelector('#help-button').addEventListener('click', () => {
  window.$hellouOne.toggle('open');
});

toggleBubbleVisibility()

$hellouOne.toggleBubbleVisibility(visibility: 'show' | 'hide')

Hides or restores the launcher bubble itself. The chat panel still works while the bubble is hidden — useful when you want to drive opening from your own UI and not show the floating launcher.

popoutChatWindow()

$hellouOne.popoutChatWindow()

Detaches the chat into a small standalone browser window (400×600). The cookie-backed conversation token is carried over, so the visitor lands in the same thread they were already in.

Identifying the user

setUser()

$hellouOne.setUser(identifier: string | number, user: object)

Attaches a known identity to the current conversation. The identifier is your stable user ID; the user object carries display fields and (in secure mode) the HMAC signature.

User fields

`name`	Display name shown to agents.
`email`	Used to match an existing contact and for outbound replies.
`avatar_url`	Absolute URL to a profile image.
`phone_number`	E.164 phone, optional.
`identifier_hash`	HMAC-SHA256 of `identifier`. Required when the inbox is in mandatory identity mode — see Identity validation.

Validation

identifier must be a string or number.
The user object must include at least one of name, email, or avatar_url.
Calling setUser with the exact same payload twice is a no-op — the SDK hashes the payload and skips the network call.

Example

window.$hellouOne.setUser('42', {
  name: 'Ada Lovelace',
  email: '[email protected]',
  avatar_url: 'https://example.com/ada.png',
  identifier_hash: '<hash from your backend>'
});

reset()

$hellouOne.reset()

Clears the visitor’s session: drops the conversation cookie, drops the cached identity, and reloads the iframe. Call this on logout. If the panel is open, it closes first.

Custom attributes

Attributes are arbitrary key–value metadata. User attributes persist across every conversation that visitor ever opens. Conversation attributes only apply to the current thread.

setCustomAttributes()

$hellouOne.setCustomAttributes(attributes: object)

Merges keys onto the visitor’s contact record. The object must contain at least one key — an empty object throws.

window.$hellouOne.setCustomAttributes({
  plan: 'pro',
  signupSource: 'partner'
});

deleteCustomAttribute()

$hellouOne.deleteCustomAttribute(name: string)

Removes a single user attribute by key.

setConversationCustomAttributes()

$hellouOne.setConversationCustomAttributes(attributes: object)

Same as setCustomAttributes, but scoped to the current conversation only. Great for capturing the URL the visitor opened chat from, their cart value, the page’s A/B variant, and so on.

deleteConversationCustomAttribute()

$hellouOne.deleteConversationCustomAttribute(name: string)

Removes a single conversation attribute by key.

Labels

setLabel()

$hellouOne.setLabel(label: string)

Tags the current conversation with a label. Labels are the same ones agents use to triage in the dashboard — useful for routing or reporting (e.g. tag every chat opened from /pricing as pricing).

removeLabel()

$hellouOne.removeLabel(label: string)

Removes a previously applied label from the conversation.

Localization & theme

setLocale()

$hellouOne.setLocale(locale: string)

Switches the widget’s UI language at runtime. Pass an ISO code like 'en', 'es', or 'fr'. Defaults to 'en' if the value is empty.

setColorScheme()

$hellouOne.setColorScheme(scheme: 'light' | 'dark' | 'auto')

Switches between light, dark, and OS-driven themes. Anything outside those three values falls back to 'light'.