Docs Pricing

Roomlio Embed JS API

BASICS

Embedding a room on your site is as simple as copy and pasting the embed code from the settings page into your site’s HTML. Some javascript will run on your site that will add a secure iframe containing your room where your users can begin conversing with others.

The embed code consists of three parts:

  1. A Roomlio div that you will place where you want the room to show (we offer different modes that don’t require you to add a div to your HTML).
  2. Two Roomlio javascript method calls, rml(‘config’) and rml(‘register’). rml(‘config’) is where you can make modifications to your room on the client side (position, languages, styles, etc). rml(‘register’) notifies our backend about the user and room so Roomlio will be ready to send and receive messages.
  3. The Roomlio javascript that runs the room on your site.

That’s it! Keep on reading below to learn more specifics about embedding a room onto your site. Please don't hesitate to reach out to Roomlio support if you have any question or need some help.

AUTHENTICATION

Roomlio provides two authentication modes. Simple and Secure (advanced)

Simple mode is useful for testing out Roomlio and some use cases where you don't need to be absolutely sure a user is who they say they are.

Secure Auth mode is highly recommended for production environments where you need to guarantee the authenticity of users. Since we use a javascript API to register the users, when not using secure mode nothing prevents a malicious user from pretending to be another user by using a browser's dev console. To implement Secure mode, base64 encode the payload using the HMAC key (provided in the Embed Code tab of the settings page for your widget) on your backend before registering the user. Then pass the result to our 'register' API call. We provide an example in the embed settings generator when Secure Auth mode is selected. The Embed Code tab for your widget also contains examples of HMAC base64 encoding in most of the popular programming languages.

Please don't hesitate to reach out to Roomlio support for help.

METHODS

Roomlio provides you with API methods that allow you to configure your rooms, pass in your user information, and more.

rml('config')

Use this to configure your Roomlio room. rml('config') must be called prior to rml('register'). This api call allows you to dynamically set configuration for widget. If values are not set here, we use the settings from the Roomlio App for the widget called by the embed code. Reasons you may want to set the configuration values dynamically would be to support multiple languages, change labels programatically and anything else you want to customize with code.

NOTE: Must be called before you call rml('register') or rml('registerSecure').

  • pk
    The pk is your "publishable key" for your Roomlio account. It identifies your embed code with your Roomlio account. It is not a secret value, but it is unique per Roomlio account. To fetch your pk select the "Get Embed Code" link for the appropriate widget on the Settings page. In the Embed Code tab you will find the pk in the Client Embed Code rml('config') call HTML.

    NOTE: Required when you set embedPosition: 'inline'.

  • roomElementID
    The "id" of the div that you have in your markup that Roomlio will replace with an embedded room. This value must be the same on all rml calls for the same widget. When embedPosition is set to bottomRight, bottomLeft, dockRight, or dockLeft, this value still needs to be present, but you do not need a corresponding div in your markup with that ID.
  • options:embedPosition
    embedPosition can be inline, bottomRight, bottomLeft, dockRight, or dockLeft.
    inlineInserts a roomlio room where you tell Roomlio to place it. In order to communicate to Roomlio where to insert the inline room, you must put a div in the page with the ID that matches the ID passed in roomElementID.
    bottomRightDisplays the embedded room in the bottom right of your webpage. By default, a chip/tab (see collapsedMode below) will appear when the room is collapsed that can be used to open the room when selected. The room will be "on top" of your page; open or collapsed.
    bottomLeftInserts the embedded room in the bottom left of your webpage. By default, a chip/tab (see collapsedMode below) will appear when the room is collapsed that can be used to open the room when selected. The room will be "on top" of your page; open or collapsed.
    dockRightTells Roomlio to put the embedded room on the right side spanning the entire height of the page. An open room will shift your page over to the left and will sit on the same plain as your page. By default, a chip/tab (see collapsedMode below) will appear when the room is collapsed that can be used to open the room when selected. The chip/tab will be "on top" of your page.
    dockLeftTells Roomlio to put the embedded room on the left side spanning the entire height of the page. An open room will shift your page over to the right and will sit on the same plain as your page. By default, a chip/tab (see collapsedMode below) will appear when the room is collapsed that can be used to open the room when selected. The chip/tab will be "on top" of your page.

    NOTE: For all embedPositions, with the exception of inline, you can hide the default chip/tab (see collapsedMode below) and use your own button/link in combination with our JS API to open and close it.

  • options:collapsedMode
    Style of the room when it's collapsed (i.e. closed). chip, tab, and hidden are the options. hidden will hide the default chip/tab in case you want to use your own button/link in combination with our JS API to open and close it. Not applicable when the embedPosition is inline.
  • options:collapsedModeOnlineLabel
    The online label of the collapsed room. Not applicable when the embedPosition is inline or collapsedMode is set to hidden.
  • options:collapsedModeOfflineLabel
    The offline label of the collapsed room. Not applicable when the embedPosition is inline or collapsedMode is set to hidden.
  • options:chatLayout
    This option changes the position of the room's messages. Choose between stacked and sideBySide. stacked messages are left justified and stack on top of each other as they come into the room. The sideBySide layout places the user's messages on the right side of the room and everyone else's on the left side. Default is stacked.
  • options:showGreetingMessage
    (optional) Set to false if you don't want to render the greeting message (the first message shown in a room). Defaults to true
  • options:showRoomMemberList
    (optional) Set to false if you don't want to render the room member list chip. Defaults to true.
  • options:unfocusedUnreadAlert
    (optional) Set to true if you want to render a visual alert in embedded room when the room has a new message and is not in focus. Default is false. The alert will disappear after the user focuses on the room.
  • options:unfocusedUnreadAlertMessage
    (optional) Message on the unread message alerts above. Defaults to "Unread Messages".
  • options:unfocusedUnreadAlertFlashTime
    (optional) The time in seconds before the unread alert flashes. Default is 30 seconds. Set to large number if you don't want flashing alerts.
  • options:greetingMessageUsername
    (optional) This is the username displayed in the greeting message. (first message displayed to a user on an embedded chat room).
  • options:greetingMessage
    (optional) The first messages shown when a user opens an embedded chat room.
  • options:offlineGreetingMessage
    Text shown above the offline message form telling the user that you're offline.
  • options:offlineMessageFields
    (optional) You can change the labels of the offline form fields, make them required or not-required, and show or hide them. Each field has a label, required, and enabled property that can be adjusted. The presence of offlineMessageFields in the rml('config') call will override all fields set in your widget's "Offline Mode" tab in the app settings. Below is an example of the offlineMessageFields object:
  • options:offlineSendButton
    (optional) Text of the offline message form submit button.
  • options:offlineThankYou
    (optional) Message displayed in the room after a visitor submits the offline form.
  • options:offlineForwardingEmail
    (optional) Email to forward offline messages.
  • options:offlineSubject
    (optional) Subject of the email sent to the offlineForwardingEmail.
  • options:styles
    (optional) You can override certain styles in the embedded room. Here are the allowed overrides:
    --rml-btn-primary-background-colorBackground color of primary buttons (i.e. offline form submit button)
    --rml-btn-primary-background-color-hoverBackground color of hovered primary buttons
    --rml-btn-primary-background-color-activeBackground color of selected primary buttons
    --rml-btn-primary-text-colorText color of primary buttons
    --rml-btn-secondary-background-colorBackground color of secondary buttons (i.e. message edit buttons)
    --rml-btn-secondary-background-color-hoverBackground color of a hovered secondary buttons
    --rml-btn-secondary-background-color-activeBackground color of selected/active secondary buttons
    --rml-btn-secondary-text-colorText color of secondary buttons
    --rml-collapsed-background-colorBackground color of the chip or tab of the collapsed room
    --rml-collapsed-background-color-hoverBackground color of the hovered chip or tab of the collapsed room
    --rml-collapsed-background-color-activeBackground color of the selected/active chip or tab of the collapsed room
    --rml-collapsed-text-colorText color of the chip or tab of the collapsed room
    --rml-font-familyFont-family for the room
    --rml-icon-themeChoose between dark or light themed icons in the room
    --rml-link-colorColor of links and link URLs
    --rml-link-color-hoverColor of hovered links and link URLs
    --rml-msg-text-colorColor of the msg text
    --rml-msg-background-colorColor of the msg background
    --rml-msg-background-color-hoverBackground color of a hovered msg
    --rml-msg-system-text-colorColor of the msg system text (i.e. timestamp)
    --rml-msg-system-text-background-colorBackground color of the msg system text
    --rml-msg-system-font-familyFont family of the msg system text
    --rml-msg-system-font-sizeFont size of the msg system text
    --rml-msg-system-border-radiusBorder radius of the msg system text
    --rml-ui-chrome-background-colorBackground color of the room chrome
    --rml-ui-chrome-text-colorText color of the room chrome
    --rml-unfocused-unread-background-colorBackground color of the alert that displays if the room has a new message and isn't focused.
    Only applies when unfocusedUnreadAlert: true
    --rml-unfocused-unread-colorText color of the alert that displays if the room has a new message and isn't focused.
    Only applies when unfocusedUnreadAlert: true
    --rml-side-by-side-them-text-colorText color of other users' messages.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-them-link-colorText color of other users' links.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-them-background-colorBackground color of other users' messages.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-me-text-colorText color of the user's messages.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-me-link-colorText color of the user's links.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-me-background-colorBackground color of the user's messages.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-border-radiusBorder radius for all side-by-side messages.
    Only applies when chatLayout: 'sideBySide'
    --rml-side-by-side-paddingPadding on all side-by-side messages.
    Only applies when chatLayout: 'sideBySide'

    NOTE: styles keys and values need to be strings. Styles that have color values can be hexidecimal, rgb, rgba, hsl, or color keywords (i.e. just like CSS).

    NOTE: --rml-collapsed-... overrides do not apply to inline rooms (aka embedPosition: 'inline').

    NOTE: CSS styles will not work for --rml-icon-theme

    NOTE: If you would like to override something not in this list, feel free to reach out and request an override!

rml('config', {
  pk: '<your pk here>', // REQUIRED only if embedPosition: 'inline'
  roomElementID: 'rml-room-1', // REQUIRED
  widgetID: '<your widgetID here>',
  options: {
    embedPosition: 'inline', // 'inline', 'bottomRight', 'bottomLeft', 'dockRight', or 'dockLeft'
    collapsedMode: 'tab', // 'chip', 'tab', or 'hidden'; not used for embedPosition: 'inline'
    collapsedModeOnlineLabel: 'How can we help you?', // not used for embedPosition: 'inline'
    collapsedModeOfflineLabel: 'Contact Us.', // not used for embedPosition: 'inline'
    chatLayout: 'stacked', // 'stacked' or 'sideBySide'
    showGreetingMessage: true, // defaults to true, if false, no need to provide greetingMessageUsername/greetingMessage
    showRoomMemberList: true, // defaults to true, false will hide the chip and sidebar showing users in a room
    unfocusedUnreadAlert: true, // optionally show an alert in room if there is a new message and room not in focus
    unfocusedUnreadAlertMessage: 'Unread Messages', // label on optional unread alert 
    unfocusedUnreadAlertFlashTime: 30, // time in seconds before alert starts to flash
    greetingMessageUsername: 'Support Team',
    greetingMessage: 'Welcome to Example. :wave: Type a message below if you have any questions!',
    offlineGreetingMessage: 'Hi, we are not around right now. Leave us a message and we will get back to you.',
    offlineMessageFields: {
      message: { label: 'Message', required: true, enabled: true },
      email: { label: 'Email', required: true, enabled: true },
      name: { label: 'Name', required: false, enabled: true },
      opt1: { label: 'Company', required: false, enabled: true },
      opt2: { label: 'Favorite Band', required: false, enabled: true },
      opt3: { label: 'Address', required: false, enabled: true },
    },
    offlineSendButton: 'Send',
    offlineThankYou: 'Thank you for sending your message! We will get back to you shortly!',
    offlineForwardingEmail: '<your email address>',
    offlineSubject: 'New Roomlio offline message',
    styles: { 
      // button styles
      '--rml-btn-primary-background-color': 'purple',
      '--rml-btn-primary-background-color-hover': 'darkPurple',
      '--rml-btn-primary-background-color-active': 'lightPurple',
      '--rml-btn-primary-text-color': '#fff',
      '--rml-btn-secondary-background-color': 'lightGray',
      '--rml-btn-secondary-background-color-hover': 'gray',
      '--rml-btn-secondary-background-color-active': '#222222',
      '--rml-btn-secondary-text-color': 'white',
      // collapsed mode styles (do not apply when embedPosition equals 'inline')
      '--rml-collapsed-background-color': 'rgba(255, 0, 0, 1)',
      '--rml-collapsed-background-color-hover': 'darkRed',
      '--rml-collapsed-background-color-active': '#8e4e4e',
      '--rml-collapsed-text-color': 'rgb(255, 255, 255)',
      // font styles
      '--rml-font-family': 'Courier, monospace, serif',
      '--rml-icon-theme': 'light', // 'light' or 'dark'
      '--rml-link-color': 'rgba(0, 255, 0, 1)',
      '--rml-link-color-hover': 'darkGreen',
      // message styles
      '--rml-msg-text-color': '#212121',
      '--rml-msg-background-color': '#fff',
      '--rml-msg-background-color-hover': '#dddddd',
      // message system styles (i.e. timestamps, 'edited' label)
      '--rml-msg-system-text-color': 'white', 
      '--rml-msg-system-text-background-color': 'gray',
      '--rml-msg-system-text-font-family': 'Courier, monospace, serif',
      '--rml-msg-system-text-font-size': '9px',
      '--rml-msg-system-text-border-radius': '4px',
      // UI chrome styles
      '--rml-ui-chrome-background-color': 'gray',
      '--rml-ui-chrome-text-color': '#212121',
      // unread message alert styles
      '--rml-unfocused-unread-background-color': 'red',
      '--rml-unfocused-unread-color': 'black',
      // side-by-side styles (only apply when chatLayout: 'sideBySide')
      '--rml-side-by-side-them-text-color': 'white',
      '--rml-side-by-side-them-link-color': '#ccc',
      '--rml-side-by-side-them-background-color': '#ff0000',
      '--rml-side-by-side-me-text-color': '#fff',
      '--rml-side-by-side-me-link-color': 'gray',
      '--rml-side-by-side-me-background-color': '#0000ff',
      '--rml-side-by-side-border-radius': '4px',
      '--rml-side-by-side-padding': '2px 6px',
    },
  },
});
rml('register')

Registers the user and room. Must be called after a `rml('config')`. All "options" are optional for `register`. See the Embed Code tab via the "Get Embed Code" link for the appropriate widget on the Settings page for different combinations. If you just provide a username, we will display that for user name. If you provide first/last name as well, we will use that for display name instead. If roomKey/roomName is left off, we will name the room after the geo location of the user. Again, it is best to refer to the Embed Code tab for the widget on the Settings page for all the different combinations.

  • roomElementID
    The "id" of the div that you have in your markup that Roomlio will replace with an embedded room. This value must be the same on all rml calls for the same widget. When embedPosition is set to bottomRight, bottomLeft, dockRight, or dockLeft, this value still needs to be present, but you do not need a corresponding div in your markup with that ID.
  • options:userID
    Your internal user id, or something that uniquely identifies the user to Roomlio
  • options:username
    Username of user, will be shown if no first/last name provided
  • options:first
    First name of user
  • options:last
    Last name of the user
  • options:roomKey
    A unique key to identify a room. Different keys mean different rooms. If a room key is changed, the embed code will generate an entirely new room. Generally your room keys should never change, but you can change roomName and maintain same room. Eg. If you have different rooms for each account in your system, your account ID would be the room key.
  • options:roomName
    Display name of the room shown to users in the sidebar of the Roomlio App
  • options:traits
    Traits are the place to send in your custom data. They can be anything you want to display in users' profiles. Note: email in the traits object will get special treatment. For instance, we will prepopulate it in the email input of the room offline form.
rml('register', {
  roomElementID: 'your-div-id-to-replace-with-embedded-room',
  options: {
    // All options are "optional" for `register`. See https://app.roomlio.dev/#/settings for different combinations
    userID: 'abc1234',
    username: 'jsmith99',
    first: 'John',
    last: 'Smith',
    roomKey: 'kraken1234',
    roomName: 'Kraken-Hockey',
    traits: {
      color: 'purple',
      account: 'acct1234',
      plan: 'pro',
      email: 'jsmith@example.com',
    },
  },
});
rml('open')

Open the room. Handy if you decide to use your own button/link to open the room. Not applicable if you set embedPosition: 'inline'. This call will be a must if you set collapsedMode: 'hidden'.

rml('open', {
  roomElementID: 'rml-room-1', // id of room you want to open
});
rml('close')

Close the room. Handy if you decide to use your own button/link to close the room. Not applicable if you set embedPosition: 'inline'.

rml('close', {
  roomElementID: 'rml-room-1', // id of room you want to close
});
rml('reset')

Clears local cache settings in the embedded room which may be useful for debugging Roomlio embed code as a developer.

rml('reset', {
  roomElementID: 'rml-room-1', // id of room in which you want clear the local cache.
});
EVENTS
rml-event

Roomlio will emit a rml-event event when certain actions relating to a room occur that will aid you in integrating a room into your website. You just have to add an event listener and listen for what type of event it is (see below).

// Example of how to listen for the rml-event
document.addEventListener('rml-event', (event) => {
  switch (event.detail.type) {
    case 'rml_opened':
      // Do something...
      break;
    case 'rml_closed':
      // Do something...
      break;
    case 'rml_state_change':
      // Do something...
      break;
    case 'rml_new_msg':
      // Do something...
      break;
    case 'rml_new_focus':
      // Do something...
      break;
    case 'rml_new_focusout':
      // Do something...
      break;
  }
});