Beacon JavaScript API

The Beacon JS API exposes the following methods to the global object: Beacon. You can use them to control your Beacon programmatically.

Beacon(‘init’, beaconId)

Call this method to load the Beacon. Additional configuration methods must be called in a separate string or object.

Beacon('init', 'YOUR_BEACON_ID_HERE')

Beacon(‘init’, config)

Alternatively, you can pass a configuration object to init. The object requires a beaconId field and accepts all fields from Beacon(‘config’).

Beacon('init', {
  beaconId: 'YOUR_BEACON_ID_HERE',
  color: '#617DEC',
  display: {
    style: 'icon',
    position: 'left',
  },
})

Beacon(‘destroy’)

Unmounts the Beacon from the DOM. You can call init again to re-render it.

Beacon('destroy')

Beacon(‘open/close’)

Use these methods to manually open or close the Beacon:

Beacon('open')
Beacon('close')
Beacon('toggle')

Beacon(‘search’, query)

Searches Docs articles and loads the results screen

Beacon('search', 'hipaa')

Beacon(‘ask-question’, question)

Open a Beacon that sends a specific question automatically to AI Answers. You can trigger this method with a link, button, or many other types of actions.

Only available in Beacons with AI Answers enabled.

Beacon('ask-question', 'How do I log in?')

Beacon(‘suggest’)

Using Beacon Builder, you can suggest articles based upon the page URL.

This suggest method allows you to go one step further by programmatically allowing you to change these suggestions based on any criteria that you specify, not just URL.

Article IDs can be found in Help Scout by navigating to the article, opening it in the editor, and copying the ID from the URL. The URL is structured like this: https://secure.helpscout.net/docs/[COLLECTION ID]/article/[ARTICLE ID]/. They can also be pulled from the Docs API.

Beacon('suggest', ['DOCS_ARTICLE_ID_1', 'DOCS_ARTICLE_ID_2'])

You can also suggest URLs that are not Docs articles. This is what the syntax would need to look like for custom links:

Beacon('suggest', [
  'DOCS_ARTICLE_ID_1',
  {
    text: 'Label for the Suggestion',
    url: 'https://www.helpscout.com',
  },
  'DOCS_ARTICLE_ID_2',
])

To expand a little further… Perhaps you’d like to display localised docs articles based upon a customer’s browser language. In the below example, we detect a browser language of Spanish 🇪🇸 (“es”), and return Spanish articles:

var language = navigator.language
if (language === 'es') {
  Beacon('suggest', [
    'SPANISH_DOCS_ARTICLE_ID_1',
    'SPANISH_DOCS_ARTICLE_ID_1',
    'SPANISH_DOCS_ARTICLE_ID_1',
  ])
})

API Limits

You can include a maximum of ten (10) Article suggestions in the suggest method.

Beacon(‘article’)

There are many ways to open a Docs Article with Beacon via any element on your site, and you can choose to do it using a custom HTML data attribute, or with a the article JavaScript method.

All you’ll need is the Article’s ID, which can be found in Help Scout by navigating to the article, opening it in the editor, and copying the ID from there. They can also be pulled from the Docs API. The editor URL is structured like this:

https://secure.helpscout.net/docs/[COLLECTION ID]/article/[ARTICLE ID]/.

Using data attributes

Data attributes are the simplest way to open a Docs Article via any link or button on your site. There are four different attributes you can choose from, which can be used to open the article in Beacon, or in a popover, sidebar, or modal. Check out the examples and demos below for more information on how to use them.

Example

<!-- Open Article in Beacon -->
<a href="#" data-beacon-article="ARTICLE_ID"></a>

<!-- Open Article in a popover -->
<a href="#" data-beacon-article-inline="ARTICLE_ID"></a>

<!-- Open Article in a sidebar -->
<a href="#" data-beacon-article-sidebar="ARTICLE_ID"></a>

<!-- Open Article in a modal -->
<a href="#" data-beacon-article-modal="ARTICLE_ID"></a>

Demos

• Use the data-beacon-article attribute to open the article in Beacon.
• Use the data-beacon-article-inline attribute to open the article in a popover.
• Use the data-beacon-article-sidebar attribute to open the article in a sidebar.
• Use the data-beacon-article-modal attribute to open the article in a modal.

Using the JS API Method

Alternatively, you can use the Beacon('article') method to open the Article within Beacon, or in a sidebar or modal. This is helpful when your trigger is something other than a link or a button, or when you’d like the article to show up automatically using your own custom logic.

Note: If the Beacon is closed when this method is called, it will also open the Beacon automatically.

Example

// Open Article in Beacon
Beacon('article', 'ARTICLE_ID')

// Open Article in a sidebar
Beacon('article', 'ARTICLE_ID', { type: 'sidebar' })

// Open Article in a modal
Beacon('article', 'ARTICLE_ID', { type: 'modal' })

Troubleshooting

There are some cases in which the data-beacon-article attributes do not work correctly, such as when the anchor tag has other tags inside it (like a span, div or i). As a workaround, you can always use this approach:

<a href="javascript:void(0)" onclick="Beacon('article', 'DOCS_ARTICLE_ID')"></a>

Beacon(‘navigate’, route)

Navigates to a specific screen. Available routes are:

Beacon('navigate', '/') // Welcome screen
Beacon('navigate', '/ask/') // Ask screen
Beacon('navigate', '/ask/message/') // Message screen
Beacon('navigate', '/ask/chat/') // Chat screen
Beacon('navigate', '/answers/') // Answers screen
Beacon('navigate', '/ai-answers/') // AI Answers screen
Beacon('navigate', '/previous-messages/') // Previous Conversations screen
Beacon('navigate', '/docs/search?query=help') // === Beacon('search')

Beacon(‘identify’, userObject)

The identify method serves four purposes:

1. It creates a new customer profile for each visitor that opens your Beacon. If a customer profile already exists, it will update the existing profile for that visitor.

2. It tells Beacon that we know the name and email address of the visitor. We use their name and email address to pre-populate and hide the fields on the ‘Create a message’ screen. We also use their name and email address to skip asking these questions at the start of a Beacon chat.

3. It can be used to record custom data attributes that can be synced as Customer Properties and Company Properties and used to trigger Messages. The attribute keys must exactly match existing Customer Property IDs or Company Property IDs (including capitalization) and value types must match the types associated with the linked Properties. Company Properties should be passed within a companyProperties object. (Customer Properties are available on current Standard, Plus, and Pro plans. Company management is available on Plus and Pro plans. Learn more here.).

4. If a valid signature is provided, it can be used to authenticate a user in Secure Mode and retrieve their previous conversations. Secure Mode ensures that the visitor is who they say they are.

Note: if the “ask for a name” flag is flipped to required for a particular Beacon, the customer must have a valid name provided in the identify request, or provide the name themselves. Passing a space character as a name will return a 400 error and prevent the user from submitting their request.

Code examples

Identify a user in Normal Mode:

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
})

Directly update the customer’s Help Scout profile as well by sending values for the company, jobTitle, and avatar attributes:

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  company: "Steve's Tyres",
  jobTitle: 'Tyre Aficionado',
  avatar: 'URL_TO_AVATAR_HERE',
})

Identify a user in Secure Mode:

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  signature: 'YOUR_SERVER_GENERATED_SIGNATURE_HERE',
})

Identify a user in Secure Mode and log Customer Properties (if there are matching Customer Properties in the account):

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  signature: 'YOUR_SERVER_GENERATED_SIGNATURE_HERE',
  Subscription: 'Free Plan',
  'Favorite-Movie': 'Zoolander',
})

Remove a Customer Property value by setting its value to an empty string:

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  signature: 'YOUR_SERVER_GENERATED_SIGNATURE_HERE',
  'Favorite-Movie': '',
})

This would remove the current value of the Favorite-Movie Customer Property for this customer. Keep in mind that Properties excluded from an Identify call (in this example: Subscription) are not affected by this behavior.

Company Properties

You can also pass company-level properties using the companyProperties attribute. Unlike custom attributes (which accept strings, numbers, booleans, or null), the companyProperties field must be a plain object containing key-value pairs that describe the customer’s company.

Company properties must be created in your Help Scout account before they can be used. The property keys must exactly match existing Company Property IDs (including capitalization), and the same character limits and value type requirements that apply to Customer Properties also apply to Company Properties.

Example

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  companyProperties: {
    industry: 'Technology',
    size: '50-100',
    plan: 'Enterprise'
  }
})

Remove a Company Property value by setting its value to null:

Beacon('identify', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  companyProperties: {
    plan: null
  }
})

These company properties will appear in the Help Scout company profile, providing additional context about the customer’s company.

API Limits

Beacon(‘prefill’, formObject)

This method can be used to pre-populate the “Create a message” contact form with data. You can fill any of the fields: name, email, subject, body of the message (text), and custom fields (fields). Unlike the ‘identify’ method, the name and email fields will remain visible and editable when you use the prefill method.

Note: After sending a message, the pre-filled values will be cleared from the contact form.

Beacon('prefill', {
  name: 'Steve Aoki',
  email: 'steve@aoki.com',
  subject: 'Need help with invoice',
  text: 'Hello, I need some help with my invoice',
  fields: [
    {
      id: 5678, // dropdown field ID
      value: 1234, // option ID
    },
    {
      id: 5679, // date field ID
      value: 'YYYY-MM-DD'