Customization

Beacons can be customized and manipulated in a number of ways. All customizations are applied before the initial rendering and can only happen once during the page lifecycle. To interact with the Beacon after it has been rendered, please refer to the Javascript API documentation.

.config( configObject )

The config method can be used to overwrite the default configuration object with custom values. Its only parameter is a Javascript object with attributes for all the different options listed below. All attributes in the configuration object are optional.

Since configuration can only happen before the initial rendering of the Beacon, place your call to the config method anywhere after the provided embed code. You cannot make consecutive calls to this method after the Beacon has been rendered on the page.

Config Object Attributes

Name Type Default Description
attachment Boolean true Enable or disable the "Attach a file" link in the contact form.
autoInit Boolean true Automatically render the Beacon as soon as the embed code finishes loading. Set to false to prevent this behavior.
collection String '' Articles can be limited to a single Docs Collection by specifying a single Collection ID
color String '#32a8d9' This hex value sets the theme for the Beacon. It is used for buttons, links and an icon. We recommend using a value that looks good with white text over it.
icon String 'buoy' Set the icon of the Beacon trigger button in the popover version. Valid values are beacon, buoy, message, question or search.
instructions String ' ' Display a custom message on top of the contact form.
modal Boolean false Display the Beacon as a modal instead of the default popover version.
position String 'right' Setting position to 'left' will place the Beacon on the left side of the screen
poweredBy Boolean true Show or hide the "Powered by Help Scout" label in the contact form confirmation view.
showContactFields Boolean false When contact fields such as name or email addres are pre-filled by a call to HS.beacon.identify(), they will be hidden in the contact form. These fields can be forced to display by setting showContactFields to true.
showName Boolean false The Name field in the contact form is hidden by default. Beacon will try to infer the customer's name from their email address. Setting showName to true will give them a chance to enter their name manually.
showSubject Boolean false The Subject field in the contact form is hidden by default. Setting showSubject to true will display the field. If the subject is hidden, the email subject will either default to the last search value, or a generic "email@domain sent you a message."
topArticles Boolean false Show a list of the most popular articles by default instead of the solo search box.
topics Array [ ] List of Topics to populate the `select` dropdown in the contact form. Each topic in the array should be an object with a val and a label attributes. The val attribute will be added as a tag in the Help Scout conversation. If left blank, topics will not appear in the contact form.
translation Object { } Translate or change any of the text used in the Beacon. See the Translation Object Attributes section for all the possible options.
zIndex Number 1050 Specify a custom z-index level (stack order) for Beacon and all its sub-components.

Translation Object Attributes

Attribute Default Text
searchLabel What can we help you with?
searchErrorLabel Your search timed out. Please double-check your internet connection and try again.
noResultsLabel No results found for
contactLabel Send a Message
attachFileLabel Attach a file
attachFileError The maximum file size is 10mb
fileExtensionError The file format you uploaded is not allowed.
nameLabel Your Name
nameError Please enter your name
emailLabel Email address
emailError Please enter a valid email address
topicLabel Select a topic
topicError Please select a topic from the list
subjectLabel Subject
subjectError Please enter a subject
messageLabel How can we help you?
messageError Please enter a message
sendLabel Send
contactSuccessLabel Message sent!
contactSuccessDescription Thanks for reaching out! Someone from our team will get back to you soon.

Example

// copy and paste your embed code on this line
<script>
  HS.beacon.config({
    color: '#cacaca',
    translation: {
      searchLabel: 'En que podemos ayudarte?',
      searchErrorLabel: 'Lo sentimos, hubo un error con tu busqueda'
    },
    topics: [
      { val: 'need-help', label: 'Need help with the product' },
      { val: 'bug', label: 'I think I found a bug'}
    ],
    attachment: true,
    instructions:'This is instructional text that goes above the form.'
  });
</script>