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);

Tip

You can also set this at init time via the hideBubbleOnClose config option. setHideBubbleOnClose() lets you change it dynamically.

---

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();

Note

No off() method. Use the unsubscribe function returned by on().

---

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: '[email protected]',
    name: 'Jane Smith',
    customFields: {
        plan: 'pro',
        company: 'Acme Inc',
    },
});

Tip

Pre-chat form interaction: If your workspace has a pre-chat form enabled, calling identify() with all required fields will skip the form when the visitor opens the widget. This lets you seamlessly identify logged-in users without asking them to fill out a form.

---

track(eventName, metadata?)

New

Tracks a custom event for proactive message triggers. Only events matching a configured custom_event trigger are forwarded — all others are silently dropped (no overhead).

Parameter	Type	Description
eventName	string	The event name to track (must match a proactive message trigger’s event field)
metadata	Record<string, unknown>?	Optional metadata (reserved for future use)

// Track when a visitor views the pricing table
receiveo.api.track('viewed-pricing-table');

// Track with metadata
receiveo.api.track('added-to-cart', { product: 'pro-plan', value: 49 });

Tip

Events are filtered at the loader level — only event names that match a configured proactive message trigger are forwarded to the widget iframe. This means you can call track() liberally without performance concerns.

---

getProactiveMessages()

New

Returns the list of proactive message configs loaded from your workspace settings.

Returns	Type	Description
	Array<{ id, content, engagementMessage, priority }>	Copy of the proactive message configs

const messages = receiveo.api.getProactiveMessages();
console.log(messages);
// [
//   { id: "pm-abc123", content: "Need help choosing a plan?", engagementMessage: "Let me help...", priority: 10 },
//   { id: "pm-def456", content: "Welcome back!", engagementMessage: "How can I help today?", priority: 5 },
// ]

---

showProactiveMessage(id)

New

Manually triggers a specific proactive message by ID, bypassing all trigger and frequency rules. Useful for custom integrations where you want full control over when a CTA appears.

Parameter	Type	Description
id	string	The proactive message ID (from getProactiveMessages())

// Show a specific CTA when a visitor reaches a certain step
receiveo.api.showProactiveMessage('pm-abc123');

Caution

This bypasses trigger evaluation, scheduling, and frequency rules. The message will show immediately regardless of cooldowns or whether it has been shown before. Use with care.

---

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

Register listeners with on().

ready

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

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

Tip

Safe to register late. If the widget is already ready when you call on('ready', cb), the callback fires on the next microtask — you’ll never miss it.

---

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
});