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. You can call it with a string or an object with initial configuration:

Beacon("init", "YOUR_BEACON_ID_HERE");

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(‘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 and copying the article ID from the URL. The URL is structured like this: https://secure.helpscout.net/docs/[COLLECTION ID]/article/[ARTICLE ID]/.

Beacon('suggest', ['DOCS_ARTICLE_ID_1','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 five (5) suggestions in the suggest method.

Single-page App Support

You can also call this method with no arguments to refresh the list of suggestions. This is particularly useful on a Single Page Application where a URL change doesn’t necessarily cause a page refresh; in this case you might want to refresh your suggestions based on the new URL. You can do that by simply calling:

window.onhashchange = function () {
  Beacon('suggest');
}

Beacon(‘article’)

You can use this method to open a specific Docs article within Beacon, using the article’s ID. If the Beacon is closed when this method is called, it will also open the Beacon automatically.

Article IDs can be found in Help Scout by navigating to the article and copying the article ID from the URL. The URL is structured like this: https://secure.helpscout.net/docs/[COLLECTION ID]/article/[ARTICLE ID]/.

Beacon('article', 'DOCS_ARTICLE_ID')

You can also use a data attribute if you wish to link to an article within an href. This is how it would work:

<a href="javascript:void(0)" data-beacon-article="DOCS_ARTICLE_ID">

Beacon(‘navigate’, route)

Navigates to a specific screen. Available routes are:

Beacon("navigate", "/"); // welcome screen
Beacon("navigate", "/ask/message/"); // message screen
Beacon("navigate", "/docs/search?query=help"); // === Beacon('search')

Beacon(‘identify’, userObject)

The ‘identify’ method serves three purposes:

  1. 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.

  2. It can be used to track custom data attributes that are then synced with the customer’s profile in Help Scout and displayed in the Beacon Sidebar app. You can add up to 100 attribute-value pairs to the ‘identify’ method, not just “name’ and “email”. The attributes can only take values of primitive type like string and numeric (E.g: phone: "1-999-999-9999"" or "Monthly Spend": 50.0). Complex objects are not accepted as valid attribute values (E.g: "Plan Settings": { "Additional Users": 1, Name: "Starter" }). See an example below.

  3. 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.

Identify a user in Normal Mode:

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

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 custom attributes to the Beacon Sidebar app:

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

If you want to remove a custom attribute from the Beacon Sidebar app, you can set its value to null. For example, based on the above, you could call:

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

This would remove the Favorite Movie attribute from the Beacon Sidebar app for this customer. Keep in mind that missing attributes (like in this case: Subscription) are not affected by this behavior.

N.B: Custom attributes in the Beacon Sidebar app are updated cumulatively. So, if a page hosting the Beacon is loaded and contains an attribute of attribute_1: aaa, this attribute will be displayed in the Beacon Sidebar app. If the page is reloaded, this time containing an attribute of attribute_2: bbb, the Beacon Sidebar app will update and display both of those attributes.

If the page is loaded again and contains a same attribute but with a new value, e.g: attribute_1: ccc, then the previous value of aaa will be overwritten with ccc.

API Limits

Type Limit Description
name (attribute) 80 Maximum number of characters for the value of the name attribute. E.g: "Steve Aoki" from above.
Custom attributes 10 Maximum number of custom attributes that can be displayed in the Beacon sidebar app.
Attribute label 100 Maximum number of characters for the label of any attribute. E.g: "Favourite Movie" from above.
Attribute value 200 Maximum number of characters for the value of any attribute. E.g: "Zoolander" from above.

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.

Beacon("prefill", {
  name: "Steve Aoki",
  email: "steve@aoki.com",
  subject: "Need help with invoice",
  text: "Hello, I need some help with my invoice. See attached PDF...",
  fields: [
    {
      id: 5678, // dropdown field ID
      value: 1234 // option ID
    },
    {
      id: 5679, // date field ID
      value: "YYYY-MM-DD" // YYYY-MM-DD format
    },
    {
      id: 5680, // single, multi-line, or number field ID
      value: "Question" // value expressed as a string
    }
  ]
});

Pre-filling Custom Fields

Pre-filling custom fields requires some manual mapping for field labels and values so that if they ever change in the future, your Beacon won’t break. It’s more tedious upfront, but will stand the test of time.

All custom field types require you to include the field ID. To find the field ID, click on a Custom Field in Help Scout, and you’ll see the ID in the URL: https://secure.helpscout.net/settings/custom-fields/[Mailbox ID/[Field ID].

For dropdown field types, you’ll also have to fetch the option ID so that you can pre-fill the value properly. Finding the option ID requires you to open your web inspector and select the option. Each option has markup that includes the ID, like so: data-option-id="[Option ID]".

Finally for date field types, the value will need to be in a specific format: YYYY-MM-DD.

Beacon(‘reset’)

Resets the contact form by clearing all of its fields, custom fields and attachments.

N.B: This doesn’t clear a name and email address that was previously submitted by the customer when creating a message. Those inputs will remain hidden.

Beacon('reset')

Beacon(‘logout’)

If your Beacon is in Normal Mode (you aren’t using Secure Mode), there may be a case for calling this method, which clears all data from the Beacon, including:

  • identify data
  • Device ID
  • Conversation history
Beacon('logout')

There is one available option for this method, which will end any chats in progress immediately when the method is called. By default, in progress chats are allowed to be completed.

Beacon('logout', { endActiveChat: true })

Beacon(‘config’, formObject)

This method, allows you to programmatically customize and transform Beacon in a multitude of different ways. Keep in mind that any attributes set via the ‘config’ method will override manual settings in the Beacon Builder in Help Scout. If you don’t set any values with this method, the Beacon Builder settings will be used.

General Options

Name Type Options Description
docsEnabled
Boolean true or false Enable or disable the Docs integration
messagingEnabled
Boolean true or false Enable or disable the contact options

Display Options

Name Type Options Description
style
String "icon", "text", "iconOrText", "manual" Style of the button being used to toggle the Beacon
text
String "Your button text" Customize the text in your Beacon button, if you have the "text" or "iconOrText" style enabled
textAlign
String "left" or "right" Put the text on the left or right of the icon, if using the "iconOrText" style
iconImage
String message, beacon, search, buoy, question Customize the icon shown in your Beacon, if you have the icon or iconOrText style enabled
color
String "#617DEC" Brand color for your Beacon
position
String "left" or "right" Puts your Beacon on the bottom left or bottom right of the page
zIndex
Number "99999" Update this to change the default zIndex of the Beacon

Messaging Options

Name Type Options Description
chatEnabled
Boolean true or false Enable or disable Chat
chatcustomFieldsEnabled Boolean true or false Enable or disable Custom Fields
contactFormcustomFieldsEnabled Boolean true or false Enable or disable Custom Fields
contactFormshowName Boolean true or false Display an editable Name field
contactFormshowSubject Boolean true or false Display an editable Subject field
contactFormallowAttachments Boolean true or false Enable or disable file attachments
contactFormshowGetInTouch Boolean true or false Show a contact link on the Beacon home screen
showPrefilledCustomFields boolean true or false (default) When custom field values are pre-filled, set to true to make them visible

N.B: In the above table, options such as contactFormcustomFieldsEnabled denote a nested JSON property.

Translate Options

Name Default
aDay
"a day"
addReply
"Add a reply"
addYourMessageHere
"Add your message here..."
aFewHours
"a few hours"
aFewMinutes
"a few minutes"
answer
"Answers"
ask
"Ask"
attachAFile
"Attach a file"
attachmentErrorText
"There was a problem uploading your attachment. Please try again in a moment."
attachmentSizeErrorText
"Attachments may be no larger than 10MB"
beaconButtonClose
"Close"
beaconButtonChatMinimize
"Minimize chat"
beaconButtonChatOpen
"Open chat"
cantFindAnswer
"Can’t find an answer?"
chatAvailabilityChangeMessage
"Our team’s availability has changed and there’s no longer anyone available to chat. Send us a message instead and we’ll get back to you."
chatbotAgentDisconnectedMessage
"Agent has disconnected from the chat. It’s possible they lost their internet connection, so I’m looking for someone else to take over. Sorry for the delay!"
chatbotConfirmationMessage
"Thanks! Someone from our team will jump into the chat soon."
chatbotGenericErrorMessage
"Something went wrong sending your message, please try again in a few minutes."
chatbotGreet
"Hi there! You can begin by asking your question below. Someone will be with you shortly."
chatbotInactivityPrompt
"Since the chat has gone idle, I’ll end this chat in a few minutes."
chatbotInvalidEmailMessage
"Looks like you’ve entered an invalid email address. Want to try again?"
chatbotName
"Help Bot"
chatbotPromptEmail
"Got it. Real quick, what’s your email address? We’ll use it for any follow-up messages."
chatButtonDescription
"Talk to our team in real-time"
chatButtonLabel
"Chat"
chatConnected
"Connected to Agent"
chatEndCalloutHeading
"All done!"
chatEndCalloutLink
"Return home"
chatEndCalloutMessage
"A copy of this conversation will land in your inbox shortly."
chatEnded
"Agent ended the chat"
chatEndUnassignedCalloutHeading
"Sorry about that"
chatEndUnassignedCalloutMessage
"It looks like nobody made it to your chat. We’ll send you an email response as soon as possible."
chatEndWaitingCustomerHeading
"Sorry about that"
chatEndWaitingCustomerMessage
"Your question has been added to our email queue and we’ll get back to you shortly."
chatHeadingSublabel
"We’ll be with you soon"
chatHeadingTitle
"Chat with our team"
continueEditing
"Continue writing…"
customFieldsValidationLabel
"Please complete all fields"
defaultMessageErrorText
"There was a problem sending your message. Please try again in a moment."
docsArticleErrorText
"There was a problem retrieving this article. Please double-check your internet connection and try again."
docsSearchEmptyText
"We couldn’t find any articles that match your search."
docsSearchErrorText
"There was a problem retrieving articles. Please double-check your internet connection and try again."
emailContinueConversation
"If you’ve got any other questions, feel free to hit reply and continue the conversation."
emailCopyOfDiscussion
"Here’s a copy of your discussion"
emailEndedLineItem
"Agent ended the chat"
emailGreeting
"Hey Customer"
emailHeading
"Today’s chat with Agent"
emailJoinedLineItem
"Agent joined the chat"
emailLabel
"Email address"
emailValidationLabel
"Please use a valid email address"
emailYou
"You"
endChat
"End chat"
ending
"Ending..."
escalationQuestionFeedback
"Did this answer your question?"
escalationQuestionFeedbackNo
"No"
escalationQuestionFeedbackYes
"Yes"
escalationSearchText
"Browse our help docs for an answer to your question"
escalationSearchTitle
"Keep searching"
escalationTalkText
"Talk with a friendly member of our support team"
escalationTalkTitle
"Talk to us"
escalationThanksFeedback
"Thanks for the feedback"
escalationWhatNext
"What next?"
firstAFewQuestions
"Let’s begin with a few questions"
getInTouch
"Get in touch"
history
"History"
howCanWeHelp
"How can we help?"
justNow
"Just Now"
lastUpdated
"Last updated"
mayNotBeEmpty
"May not be empty"
messageButtonLabel
"Message"
messageConfirmationText
"You’ll receive an email reply within a few hours."
messageLabel
"How can we help?"
messageSubmitLabel
"Send a message"
nameLabel
"Name"
next
"Next"
nothingFound
"Hmm…"
previousMessageErrorText
"There was a problem retrieving this message. Please double-check your Internet connection and try again."
previousMessages
"Previous messages"
received
"Received"
relatedArticles
"Related Articles"
responseTime
"We usually respond in a few hours"
searchLabel
"What can we help you with?"
sendAMessage
"Send a message"
sendMessage
"Send message"
subjectLabel
"Subject"
suggestedForYou
"Suggested For You"
tryAgain
"Try again"
tryBroaderTerm
"Try searching a broader term, or"
uploadAnImage
"Upload an image"
viewAndUpdateMessage
"You can view and update your message in"
waitingForAnAnswer
"Waiting for an answer"
weAreOnIt
"We’re on it!"
weUsuallyRespondIn
"We usually respond in"
you
"You"

API Limits

The maximum number of characters for a Translation value is 160.

Examples

To demonstrate how the above options might be used collectively, see the example below.

Beacon('config', {
  "docsEnabled": true,
  "display": {
    "style": "icon",
    "iconImage": "search"
  },
  "messaging": {
    "chatEnabled": true,
    "chat": {
      "customFieldsEnabled": true
    }
  },
  "contactForm": {
    "customFieldsEnabled": true,
    "showName": true
  },
  "labels": {
    "chatHeadingSublabel": "We’ll be with you soon",
    "continueEditing": "Continue Editing…",
    "emailValidationLabel": "Please use a valid email address"
  }
}

Taking it a little further… Perhaps you’d like to localise Beacon and translate the text based upon a customer’s browser language? In the below example, we detect a browser language of Spanish 🇪🇸 (“es”), and translate the label accordingly:

var language = navigator.language
if (language === 'es') {
  Beacon('config', {
    labels: {
      you: 'Tú'
  })
})

Beacon(‘on/off/once’)

These methods allow you to hook up to specific events in the lifecycle of the Beacon to perform custom actions. Right now the only two supported events are ‘open’ and ‘close’, and they’ll be executed when the Beacon is opened or closed by clicking on the FAB or by calling the JS API methods. Example usage:

Beacon('on', event, callback)
Beacon('once', event, callback)
Beacon('off', event, callback?)
Beacon("on", "open", () => console.log("Beacon opened"));

Beacon("on", "close", () => console.log("Beacon closed"));

Beacon("once", "open", () => {
  console.log(
    "This will only get called the first time the open event is triggered"
  );
});

// Stop listening to a specific callback
Beacon("off", "open", callbackPreviouslyAdded);

// Stop listening to ALL callbacks for an event
Beacon("off", "open");