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

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.