Open Methods

Beyond Beacon.open(), Beacon exposes several methods that let you open the widget with specific intent — pre-populated composer text, an immediate message send, or a particular tab already in focus.

These are especially useful when you know the context a visitor is coming from: an error state, a pricing page, a checkout flow, or an onboarding step.

Beacon.open()

Opens the widget to whatever state it was last in. If it has never been opened, it opens to the home screen.

Beacon.open();

Beacon.show()

Alias for Beacon.open(). Use whichever reads more naturally in your code.

Beacon.show();

Beacon.showNewMessage(text?)

Opens the widget and puts focus on the message composer. Optionally pre-populates the composer with a string.

// Open with an empty composer
Beacon.showNewMessage();
 
// Open with pre-filled text the visitor can edit before sending
Beacon.showNewMessage('I have a question about my bill');

This is ideal for contextual support triggers — the visitor sees a relevant starting point but can still edit it before sending.

// On a pricing page
document.getElementById('pricing-question-btn').addEventListener('click', function () {
  Beacon.showNewMessage('I have a question about your pricing plans');
});
 
// After a failed form submission
function onFormError(fieldName) {
  Beacon.showNewMessage('I need help with the ' + fieldName + ' field');
}

Beacon.startConversation(message)

Opens the widget and immediately sends message as the visitor's first message, without any composer interaction. The conversation starts straight away.

Beacon.startConversation('I need help resetting my password');

Use this when you have enough context to send a useful first message automatically — for example, when a visitor clicks a button that clearly signals their intent, or when your app detects an error and should escalate immediately.

// On a failed payment
function onPaymentFailed(error) {
  Beacon.startConversation('My payment just failed with error: ' + error.code);
}
 
// On an unrecoverable app error
window.onerror = function (message) {
  Beacon.startConversation('I hit an error: ' + message);
};

The difference between showNewMessage and startConversation:

	showNewMessage	startConversation
Opens widget	Yes	Yes
Fills composer	Yes (visitor can edit)	Sends immediately
Visitor input required	Yes	No
Best for	Contextual nudges	Automated escalation

Beacon.showSpace(space)

Opens the widget directly to a specific tab.

Beacon.showSpace('home');      // Home screen
Beacon.showSpace('messages');  // Conversation list
Beacon.showSpace('articles');  // Help articles

Valid values: 'home', 'messages', 'articles'.

Use showSpace('articles') to send visitors straight to your knowledge base:

document.getElementById('search-help-btn').addEventListener('click', function () {
  Beacon.showSpace('articles');
});

Use showSpace('messages') to bring a returning visitor back to their ongoing conversation:

// After login, if the user has an open conversation
if (user.hasOpenConversation) {
  Beacon.showSpace('messages');
}

Beacon.close() and Beacon.hide()

Close the widget panel. hide() is an alias for close().

Beacon.close();
// same as:
Beacon.hide();

Full example: contextual help triggers

Beacon.boot({
  workspace_id: 'YOUR_WORKSPACE_ID',
  hide_default_launcher: true
});
 
// General help button — just open
document.getElementById('help-btn').addEventListener('click', function () {
  Beacon.open();
});
 
// Pricing page — pre-fill with context
document.getElementById('pricing-help').addEventListener('click', function () {
  Beacon.showNewMessage('I have a question about the ' + currentPlan + ' plan');
});
 
// Error state — send message immediately
document.getElementById('error-support').addEventListener('click', function () {
  Beacon.startConversation('I hit an error on the checkout page: ' + lastError);
});
 
// Help articles link
document.getElementById('view-docs').addEventListener('click', function () {
  Beacon.showSpace('articles');
});