API Reference

After the loader script runs, the widget API is available at window.receiveo.api.

Methods

`open()`

Opens the chat window and focuses the message input.

receiveo.api.open();

If the window is already open, this is a no-op (but still focuses the input).

`close()`

Closes the chat window.

receiveo.api.close();

If hideBubbleOnClose is enabled, this also hides the bubble.

`toggleWindow()`

Toggles the chat window between open and closed.

receiveo.api.toggleWindow();

`showBubble()`

New

Shows the chat bubble.

receiveo.api.showBubble();

No-op if the bubble is already visible. Emits the bubble:show event.

`hideBubble()`

New

Hides the chat bubble.

receiveo.api.hideBubble();

No-op if the bubble is already hidden. Emits the bubble:hide event.

`setHideBubbleOnClose(enabled)`

New

Toggles the hide-bubble-on-close behavior at runtime.

Parameter	Type	Description
`enabled`	`boolean`	`true` to hide bubble when chat closes, `false` to keep it visible

// Enable: closing the chat also hides the bubble
receiveo.api.setHideBubbleOnClose(true);

// Disable: closing the chat leaves the bubble visible
receiveo.api.setHideBubbleOnClose(false);

`on(event, callback)`

New

Registers an event listener. Returns an unsubscribe function.

Parameter	Type	Description
`event`	`string`	Event name — see Events below
`callback`	`() => void`	Function to call when the event fires
Returns	`() => void`	Call this to remove the listener

// Register
const unsubscribe = receiveo.api.on('open', () => {
    console.log('Chat window opened');
});

// Later, remove the listener
unsubscribe();

`identify(data)`

Identifies the current visitor as a known contact.

Parameter	Type	Description
`data.email`	`string?`	Contact email
`data.name`	`string?`	Contact name
`data.phone`	`string?`	Contact phone
`data.customFields`	`Record<string, unknown>?`	Custom fields
`data.externalId`	`string?`	External system ID
`data.externalIdProvider`	`string?`	External ID provider name

receiveo.api.identify({
    email: 'jane@example.com',
    name: 'Jane Smith',
    customFields: {
        plan: 'pro',
        company: 'Acme Inc',
    },
});

Getters

`isBubbleVisible`

New

Returns true if the chat bubble is currently visible.

if (receiveo.api.isBubbleVisible) {
    console.log('Bubble is showing');
}

`isChatWindowOpen`

New

Returns true if the chat window is currently open.

if (receiveo.api.isChatWindowOpen) {
    console.log('Chat is open');
}

Events

`ready`

Fires when the widget has fully initialized (both iframes loaded and ready).

receiveo.api.on('ready', () => {
    console.log('Widget is ready');
});

`open`

Fires when the chat window opens.

receiveo.api.on('open', () => {
    // Track in analytics, hide other UI, etc.
});

`close`

Fires when the chat window closes (for any reason — X button, Escape key, or api.close()).

receiveo.api.on('close', () => {
    // Chat window was closed
});

`bubble:show`

Fires when the bubble becomes visible (via showBubble() or default load).

receiveo.api.on('bubble:show', () => {
    // Bubble is now visible
});

`bubble:hide`

Fires when the bubble is hidden (via hideBubble() or hideBubbleOnClose behavior).

receiveo.api.on('bubble:hide', () => {
    // Bubble is now hidden
});