Docs Pricing

Roomlio API

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

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'
    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: { 
      '--rml-btn-background-color': 'rgba(255, 0, 0, 1)',
      '--rml-btn-background-color-hover': 'darkRed',
      '--rml-btn-background-color-active': '#8e4e4e',
      '--rml-btn-text-color': '#ffffff',
      '--rml-unfocused-unread-background-color': 'red',
      '--rml-unfocused-unread-color': 'black',
    },
  },
});

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

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.

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



API 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;
  }
});