What we do
Tools
Industries
Department
How we workLet's talk →
Home/Help Scout/Help Scout Beacon That Knows Who's Signed In
Help Scout

Help Scout Beacon Treats Everyone as a Stranger Until You Call identify

Beacon is Help Scout's support widget: a contact form, Docs search and chat in one small panel you embed with a JavaScript snippet. Paste the embed code and it works, but a customer who's been signed in for an hour still gets asked for their name and email. Recognizing them, and keeping their history private, takes a few calls on your side and a little code on your server.

The calls that change what Beacon knows

Install: paste the Beacon embed code from the Beacon's settings in Help Scout, or use the official WordPress plugin. It ends with Beacon('init', 'your-beacon-id').

Recognize the visitor: call Beacon('identify', { name, email, ... }) once they're signed in. Beacon fills and hides the name and email fields and updates their Help Scout customer profile.

Add context for this conversation only: Beacon('session-data', {...}) takes up to 20 label-value pairs, such as the current plan or the page they were on, and doesn't touch the profile.

Point at the right help: Beacon('suggest', [...]) sets up to 10 Docs articles or custom links for the current screen.

Out of the box versus wired to your login

Without code, Beacon is configurable in look and layout: colors, wording, which of contact, Docs and chat appear, and where it sits on the page. Every visitor sees the same widget with the same suggested articles. That's fine for a marketing site, but on a logged-in app it means agents get conversations from "unknown" senders and customers retype details you already hold.

identify fixes the first part. Beyond name and email it takes company, job title, an avatar URL and custom properties (text up to 255 characters, numbers, URLs, dates as YYYY-MM-DD, or dropdowns that must match an option label exactly), plus company-level properties. Leave a property out and it stays as it was; send an empty string and it's removed from the customer. Your own site has to make that call with the right data, because Beacon doesn't look anything up by itself.

n-frames does that wiring for Help Scout customers: identify fed from your account system the moment a page loads, session data carrying the order or account the visitor is looking at, a signing endpoint for Secure Mode, and suggestions mapped route by route. For pulling Beacon conversations into other systems once they arrive, that's the Help Scout API, and the Help Scout overview covers the help desk itself.

Turning on Secure Mode without exposing the secret

Secure Mode verifies the visitor's identity so their conversation history can follow them across devices without anyone reading it by typing someone else's email.

  1. 1

    Reveal the secret key

    In the Beacon's settings in Help Scout, open the Contact tab. Under the contact form section, switching on Enable cross-device history shows the secret key. Save the Beacon.

    Watch for: that key is a server secret. It must never appear in page source, a front-end bundle or a public repo.

  2. 2

    Sign the email on your server

    Generate a SHA-256 HMAC of the signed-in customer's email, keyed with the secret, as a hex digest. Help Scout's docs show it in Rails, PHP and Node; any back end can do it in a few lines.

  3. 3

    Pass the signature to identify

    Render the signature into the page, or return it from an authenticated endpoint, and include it as signature alongside the same email in Beacon('identify', ...). The email has to be exactly what you signed.

  4. 4

    Log out cleanly

    When the customer signs out, call Beacon('logout'), with endActiveChat if a chat might be open. reset only clears form fields; it won't clear an identified or Secure Mode visitor.

    Watch for: shared computers. Skipping logout is how the next person on the machine sees the last person's details.

A Beacon embed that half works

Suggestions stuck on the first screen of a single-page app

How you'll know: The app changes route but Beacon keeps suggesting the articles from the page it loaded on.

Fix: On each route change, send Beacon('event', { type: 'page-viewed', ... }) and call suggest again with that screen's article IDs. Article IDs are in the article's editor URL or available from the Docs API.

Custom properties silently ignored

How you'll know: identify runs, but the plan or account ID never appears on the customer profile.

Fix: Property IDs are case-sensitive and allow only letters, numbers, hyphens and underscores, and dropdown values must match an option label exactly. Match them to the properties set up in Help Scout.

identify called before anyone signs in

How you'll know: Conversations get attached to an empty or placeholder name.

Fix: Only call identify once your app knows who the user is. Before that, let Beacon ask, or use prefill to suggest values the visitor can still change.

Questions people ask

What is Help Scout Beacon?

Help Scout's embeddable support widget. It combines a contact form, a searchable Docs knowledge base and live chat, and you add it to your own site with a JavaScript snippet or Help Scout's official WordPress plugin.

Is Beacon included with Help Scout plans?

Yes, Beacon comes with a Help Scout plan rather than as a separate purchase. How much it knows about each visitor depends on the development work you put around it.

Can Beacon show logged-in customer details automatically?

Not by itself. Your site has to call Beacon('identify') with the customer's name, email and any custom properties, and session-data for details that only matter to this conversation. Once that's in place, the details arrive with every conversation without the customer typing them.

What is Secure Mode in Help Scout Beacon?

Identity verification for Beacon. Your server signs the customer's email with a secret key from the Beacon's settings, and Beacon uses that signature so only the real customer sees their conversation history across devices and browsers.

Can I embed Beacon on a WordPress or Shopify site?

WordPress, yes, through Help Scout's plugin. Since Beacon is plain JavaScript, it can also go in a Shopify theme or any custom site by pasting the embed code; identify and Secure Mode then need the same server-side work as anywhere else.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.