Ship Live Support Chat in One Script Tag - The RoomieSupport JavaScript API

Roomie's support widget works out of the box with one script tag and a floating launcher bubble. But if you are building a product, you probably want more control: your own "Chat with us" button in the navbar, the widget speaking your user's language, and your logged-in customers never re-typing their name and email.

That is what the RoomieSupport JavaScript API is for. This post is the developer reference — every script attribute, method, and event. If you haven't created a support project yet, start with the setup tutorial and come back here.

The Two Keys to Embedding

Everything hangs off two values from your project settings:

The publishable API key (pk_live_...) identifies your project. It is safe to expose in client HTML — pasting it into public page source is fine.

The allowed origins list is what actually gates access. A request is accepted only when it comes from an origin on your allow-list — one site per line, with wildcard subdomain support (https://*.example.com) and localhost for development.

If the key ever ends up somewhere it shouldn't, rotate it in settings and the old key stops working immediately.

Default Setup: One Script Tag

Paste before the closing body tag and you are done — a floating launcher appears bottom-right:

<script
  src="https://app.roomie.work/support-widget.js"
  data-api-key="pk_live_xxxxxxxxxxxxxxxx"
  data-position="bottom-right"
  data-accent="#4f46e5"
  async
></script>

• data-position — where the launcher bubble sits (e.g. bottom-right)
• data-accent — your brand color for the widget UI

Custom Setup: Your Own Button

Prefer your own trigger instead of the default bubble? Hide the launcher and drive the widget yourself:

<!-- 1. Load it with the launcher hidden, pre-configured -->
<script
  src="https://app.roomie.work/support-widget.js"
  data-api-key="pk_live_xxxxxxxxxxxxxxxx"
  data-hide-launcher="true"
  data-language="en"
  data-languages="en,th"
  data-required-fields="name,phone"
  async
></script>

<!-- 2. Your own button -->
<button onclick="RoomieSupport.toggle()">
  Chat with us <span id="cs-badge"></span>
</button>

The extra attributes:

• data-hide-launcher — suppress the default bubble entirely
• data-language — the language the widget opens in
• data-languages — which languages appear in the in-widget language menu
• data-required-fields — which identity fields a guest must fill before chatting

The Full JavaScript API

Once the script loads, a global RoomieSupport object is available.

Panel control:

• RoomieSupport.open() / .close() / .toggle() — open, close, or toggle the chat panel
• RoomieSupport.isOpen() — whether the panel is currently open
• RoomieSupport.getUnread() — current unread message count

Identity:

• RoomieSupport.setUserIdentity({ name, email, phone }) — pre-fill or set the guest identity, e.g. your logged-in user, so they are never asked again
• RoomieSupport.setRequiredFields(fields) — mandatory identity fields, e.g. ["name","phone"]. An empty array means email OR phone is enough
• RoomieSupport.reset() — forget the guest and end the session. Call this on logout

Localization:

• RoomieSupport.setLanguage(code) — set the active language, e.g. "th"
• RoomieSupport.setLanguages(codes) — curate the in-widget language menu, e.g. ["en","th"]
• RoomieSupport.setLocalization(dict) — supply custom translations as { th: {...}, en: {...} }
• RoomieSupport.setLanguageSelectorVisible(bool) — show or hide the language menu
• RoomieSupport.getDefaultLocalization() — returns the full English dictionary to translate from

Events:

• roomie:support:unread — fired on window whenever the unread count changes; the count is in event.detail.count

Putting It Together

A realistic integration for an app with signed-in users:

<script>
  // Identify the signed-in user (skips asking again)
  RoomieSupport.setUserIdentity({
    name: "Jane Doe", email: "[email protected]"
  });

  // Badge your own button with the unread count
  window.addEventListener("roomie:support:unread", function (e) {
    document.getElementById("cs-badge").textContent = e.detail.count || "";
  });

  // Localization: supply Thai translations, open in Thai
  RoomieSupport.setLocalization({
    th: { startChat: "<your Thai translation>" }
  });
  RoomieSupport.setLanguage("th");

  // On logout, end the guest session
  RoomieSupport.reset();
</script>

What teams build with this:

• A Support link in the navbar or help center that calls RoomieSupport.open(), badged live with the unread event
• Auto-identified users — logged-in customers never re-type their details, and the conversation is linked to the right person
• Fully localized widgets per market, down to every string
• Verified phone before chat — the phone field is a full international input with format validation, so support teams that call customers back get a real number

Consent and What Happens After

Before connecting, the visitor fills in their details and must tick the consent / recording notice — only then can the chat start, so every conversation begins with explicit consent on record.

The chat then lands in your project inbox with a waiting status and a readable ref like CS-10. An agent claims it, alerts route to them alone, and the conversation flows: waiting → claimed → active → resolved. The guest can reopen it anytime from their saved history.

If you have AI auto-reply enabled, the AI takes the first response and hands off to your team when needed — how to configure that, plus working hours and email branding, is covered in the setup tutorial.

Start Building

One script tag gets you live chat. A dozen small methods make it feel native to your product. Create a free Roomie workspace, set up a support project, and your widget can be answering customers today — see the customer support feature page for the full picture.