RelayDocs

Support widget

Identify your users

When your app tells the widget who is signed in, every conversation arrives in your inbox with their name, email and account details. No more “what’s the email on your account?”.

RelaySettings#

Set window.RelaySettings before the widget.js script tag. Every field is optional.

userIdstringoptional
Your own id for the user. Stored on the customer record as their external id.
namestringoptional
Shown in the inbox, and used to greet them in the widget (“Hi Jane 👋”).
emailstringoptional
Lets you follow up by email, and lets Relay email unread replies. When it’s set, the widget never asks for an email before a handoff.
metaRecord<string, string>optional
Anything useful when helping them, such as plan, company or signup date. It is shown in the customer sidebar in the inbox. New keys are merged into what was already stored.
html
<script>
  window.RelaySettings = {
    userId: currentUser.id,
    name: currentUser.name,
    email: currentUser.email,
    meta: {
      plan: currentUser.plan,          // "Pro"
      company: currentUser.company,    // "Northwind"
      seats: String(currentUser.seats) // values are strings
    }
  };
</script>

After sign-in#

If the user signs in after the page has loaded, as in most single-page apps, send the same fields with the JavaScript API:

js
window.Relay("identify", { userId: user.id, name: user.name, email: user.email, meta: { plan: user.plan } });

Anonymous visitors#

Without identity, the widget still works. The visitor keeps an anonymous id in their browser. If they ask to talk to a human, the widget asks for their name and email once, so you can reply even after they leave.

Identity comes from the browser

RelaySettings is set by your page’s JavaScript, so a technical user could change it. Treat it as helpful context for support, not as proof of who someone is. Never take account actions (refunds, email changes) based on it alone.