Messenger

Messenger JavaScript API

Control the Messenger from your site or app with window.Rabbitblaze: identify signed-in users, open it from your own UI and track what people do.

Install

Paste the snippet before </body> on every page (your snippet, with your app ID filled in, is in Settings → Messenger → Install, with React, Vue and Google Tag Manager variants). It loads loader.js after your page, so it never slows it down, and queues any Rabbitblaze(…) calls made before it arrives.

index.html

<script>  window.rabbitblazeSettings = {    app_id: "YOUR_APP_ID",    // Signed-in users (optional):    // user_id: "48213",    // email: "[email protected]",    // name: "Lena Fischer",    // created_at: 1709892000,    // user_hash: "<HMAC-SHA256 of user_id, computed on your server>",  };  (function () {    var w = window;    if (typeof w.Rabbitblaze !== "function") {      var q = function () { q.q.push(arguments); };      q.q = [];      w.Rabbitblaze = q;    }    function load() {      var s = document.createElement("script");      s.async = true;      s.src = "https://widget.rabbitblaze.com/loader.js";      document.head.appendChild(s);    }    if (document.readyState === "complete") load();    else w.addEventListener("load", load, false);  })();</script>

With window.rabbitblazeSettings set, the Messenger boots by itself. Without it, call Rabbitblaze("boot", settings) when you’re ready — usually right after you know who is signed in.

Settings

boot, update and window.rabbitblazeSettings take the same snake_case settings. Visitors are leads until you identify them with user_id (or email) and a valid user_hash.

app_id string required: Your workspace’s app ID (Settings → Messenger → Install).
user_id string | number: Your product’s id for the signed-in user.
email string: The user’s email.
name string: Full name.
user_hash string: HMAC-SHA256 of user_id (or email) — see identity verification.
created_at number | string: When they signed up: Unix seconds, milliseconds or ISO-8601.
phone string: Phone number.
avatar string | object: Image URL, or { type: "avatar", image_url }.
company object: { id, name, …attributes } (company_id works too). Links a verified user to the company.
language_override string: Messenger language, e.g. de. Defaults to the browser’s.
hide_default_launcher boolean: Hide the round launcher (open the Messenger from your UI).
custom_launcher_selector string: CSS selector of your own elements that open the Messenger.
alignment "left" | "right": Launcher side, overriding the workspace setting.
horizontal_padding number: Launcher distance from the side, 20–400 px.
vertical_padding number: Launcher distance from the bottom, 20–400 px.
any other key string | number | boolean: Stored as a custom attribute on the person (keys like plan, up to 100). Attributes marked protected in Messenger security settings can only be set from your server.

Commands

Every command is a call to the global function: Rabbitblaze(command, …arguments).

`boot`

Starts the Messenger with the given settings. Calling it again for the same person updates them; for someone else it shuts the first session down and starts a new one. Not needed when you set window.rabbitblazeSettings before the script loads.

Rabbitblaze("boot", settings)

Rabbitblaze("boot", { app_id: "YOUR_APP_ID", user_id: "48213", user_hash: "…" })

`update`

Merges new settings and sends them to Rabbitblaze (debounced by 300 ms): updates the person’s attributes and refreshes proactive messages. Switching an identified user to someone else starts a new session.

Rabbitblaze("update", settings?)

Rabbitblaze("update", { plan: "enterprise", seats: 40 })

`shutdown`

Ends the session, removes the Messenger from the page and forgets the visitor id stored on this device. Call it when someone signs out.

Rabbitblaze("shutdown")

Rabbitblaze("shutdown")

`show`

Opens the Messenger on its current screen.

Rabbitblaze("show")

Rabbitblaze("show")

`hide`

Closes the Messenger.

Rabbitblaze("hide")

Rabbitblaze("hide")

`showSpace`

Opens a space: home, messages, help, news or tickets (unknown values open Home).

Rabbitblaze("showSpace", space)

Rabbitblaze("showSpace", "help")

`showMessages`

Opens the list of the person’s conversations.

Rabbitblaze("showMessages")

Rabbitblaze("showMessages")

`showNewMessage`

Opens a new conversation, optionally with the composer pre-filled.

Rabbitblaze("showNewMessage", text?)

Rabbitblaze("showNewMessage", "I have a question about my invoice")

`showArticle`

Opens a Help Center article inside the Messenger (the Help space without an id).

Rabbitblaze("showArticle", id)

Rabbitblaze("showArticle", "0199b1d0-8c9d-7e0f-9a1b-2c3d4e5f6a7b")

`showNews`

Opens a news item, or the News space without an id.

Rabbitblaze("showNews", id?)

Rabbitblaze("showNews")

`showTicket`

Opens one of the person’s tickets, or the Tickets space without an id.

Rabbitblaze("showTicket", id?)

Rabbitblaze("showTicket", "0199c521-4c5d-7e6f-9a7b-8c9d0e1f2a3b")

`trackEvent`

Records an event for the current person — for segments, outbound triggers and goals, workflows and their timeline. Metadata is an object (up to 20 keys, 8 KB).

Rabbitblaze("trackEvent", name, metadata?)

Rabbitblaze("trackEvent", "invited-teammate", { count: 3 })

`getVisitorId`

Returns the anonymous visitor id of this device (a string, or null before boot). Useful to link a visitor’s conversations to the account they create.

Rabbitblaze("getVisitorId")

const visitorId = Rabbitblaze("getVisitorId")

`onShow`

Calls callback() whenever the Messenger opens.

Rabbitblaze("onShow", callback)

Rabbitblaze("onShow", () => analytics.track("Messenger opened"))

`onHide`

Calls callback() whenever the Messenger closes.

Rabbitblaze("onHide", callback)

Rabbitblaze("onHide", () => analytics.track("Messenger closed"))

`onUnreadCountChange`

Calls callback(count) when the number of unread messages changes — for your own badge.

Rabbitblaze("onUnreadCountChange", callback)

Rabbitblaze("onUnreadCountChange", (count) => updateBadge(count))

Single-page apps

Page changes made with the History API (pushState, replaceState, back/forward) and hash changes are reported automatically, so outbound messages that target URLs keep working. Tie the Messenger to your sign-in state:

app.js

// After sign-in (identity verified with user_hash from your server):Rabbitblaze("boot", {  app_id: "YOUR_APP_ID",  user_id: user.id,  email: user.email,  name: user.name,  created_at: user.signedUpAt, // Unix seconds or an ISO-8601 string  user_hash: user.rabbitblazeHash,  company: { id: account.id, name: account.name, plan: account.plan },  plan: "business", // any other key becomes a custom attribute}) // When their details change:Rabbitblaze("update", { seats: 14 }) // On sign-out — clears the session so the next person starts fresh:Rabbitblaze("shutdown")

Visitors and privacy

The Messenger itself runs in iframes served from https://widget.rabbitblaze.com, isolated from your page. The small loader script on your page only manages those frames, reports page changes and keeps the visitor id.
A random visitor id is kept in localStorage and a first-party cookie named rb_visitor_id, so visitors keep their conversations across visits. shutdown forgets it.
Restrict where the Messenger may run with trusted domains in Settings → Messenger → Security.