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:

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).
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.
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.

`inline`	Inserts 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`.
`bottomRight`	Displays 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.
`bottomLeft`	Inserts 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.
`dockRight`	Tells 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.
`dockLeft`	Tells 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-color`	Background color of primary buttons (i.e. offline form submit button)
`--rml-btn-primary-background-color-hover`	Background color of hovered primary buttons
`--rml-btn-primary-background-color-active`	Background color of selected primary buttons
`--rml-btn-primary-text-color`	Text color of primary buttons
`--rml-btn-secondary-background-color`	Background color of secondary buttons (i.e. message edit buttons)
`--rml-btn-secondary-background-color-hover`	Background color of a hovered secondary buttons
`--rml-btn-secondary-background-color-active`	Background color of selected/active secondary buttons
`--rml-btn-secondary-text-color`	Text color of secondary buttons
`--rml-collapsed-background-color`	Background color of the chip or tab of the collapsed room
`--rml-collapsed-background-color-hover`	Background color of the hovered chip or tab of the collapsed room
`--rml-collapsed-background-color-active`	Background color of the selected/active chip or tab of the collapsed room
`--rml-collapsed-text-color`	Text color of the chip or tab of the collapsed room
`--rml-font-family`	Font-family for the room
`--rml-icon-theme`	Choose between `dark` or `light` themed icons in the room
`--rml-link-color`	Color of links and link URLs
`--rml-link-color-hover`	Color of hovered links and link URLs
`--rml-msg-text-color`	Color of the msg text
`--rml-msg-background-color`	Color of the msg background
`--rml-msg-background-color-hover`	Background color of a hovered msg
`--rml-msg-system-text-color`	Color of the msg system text (i.e. timestamp)
`--rml-msg-system-text-background-color`	Background color of the msg system text
`--rml-msg-system-font-family`	Font family of the msg system text
`--rml-msg-system-font-size`	Font size of the msg system text
`--rml-msg-system-border-radius`	Border radius of the msg system text
`--rml-ui-chrome-background-color`	Background color of the room chrome
`--rml-ui-chrome-text-color`	Text color of the room chrome
`--rml-unfocused-unread-background-color`	Background 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-color`	Text 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-color`	Text color of other users' messages. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-them-link-color`	Text color of other users' links. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-them-background-color`	Background color of other users' messages. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-me-text-color`	Text color of the user's messages. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-me-link-color`	Text color of the user's links. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-me-background-color`	Background color of the user's messages. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-border-radius`	Border radius for all side-by-side messages. Only applies when `chatLayout: 'sideBySide'`
`--rml-side-by-side-padding`	Padding 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;
  }
});

rml_opened
When a room is opened the rml_opened event is emitted. Does not emit when rml('config') has embedPosition: 'inline'
```
// rml_opened object
{
  type: 'rml_opened',
  payload: {
    roomElementID: '<room-element-id>'
  }
}
```
rml_closed
When a room is closed the rml_closed event is emitted. Does not emit when rml('config') has embedPosition: 'inline'
```
// rml_closed object
{
  type: 'rml_closed',
  payload: {
    roomElementID: '<room-element-id>'
  }
}
```
rml_state_change
Emits when the room's associated widget transitions on or off. It also emits when the room is initialized so the initial state can be known w/o the widget actually being turned on or off. Useful to trigger an online or offline state of the custom button on your website.
```
// rml_state_change object
{
  type: 'rml_state_change',
  payload: {
    state: 'on'
  }
}
```

rml_new_msg

Emits when a new message is received in a room. Can be used to display your own new message count or notification on your website.

// rml_new_msg object
{
  type: "rml_new_msg"
  payload: {
    currentUserEmbed: "<current-user-id>",
    msg: {
      body: "Do you have a question?"
      createdAt: "2021-01-21T20:12:18.302159Z"
      editedAt: "0001-01-01T00:00:00Z"
      first: "Winston"
      id: "<msg-id>"
      last: "Smith"
      links: []
      roomID: "<room-id>"
      roomName: "support-room"
      tmpID: "<tmp-id>"
      userID: "<user-id>"
      userType: "member"
      username: "winstonSmith"
    }
  }
}

rml_new_focus
When the room is focused the rml_new_focus event will be emitted. Handy if you want to clear your own new message count or notifications on your site.
```
// rml_new_focus object
{
  type: 'rml_new_focus',
  payload: {
    roomElementID: '<room-element-id>';
  }
}
```

rml_new_focusout

When the room is unfocused the rml_new_focusout event will be emitted.

// rml_new_focus object
{
  type: 'rml_new_focusout',
  payload: {
    roomElementID: '<room-element-id>';
  }
}