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 roomElementID: 'rml-room-1', // REQUIRED widgetID: '<your widgetID here>', options: { chipOnlineLabel: 'Question? Chat with us live now.', // for sidebar only chipOfflineLabel: 'Question? Contact us.', // for sidebar only embedPosition: 'inline', // 'inline' or 'sidebar' greetingMessageUsername: 'Support Team', greetingMessage: 'Welcome to Example. :wave: Type a message below if you have any questions!', offlineMessage: "Sorry we're not available at the moment.", offlineContactEmail: '<your email address>', }, });
NOTE: Must be called before you call rml('register')
or rml('registerSecure')
.
- pkThe
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 yourpk
select the "Get Embed Code" link for the appropriate widget on the Settings page. In the Embed Code tab you will find thepk
in the Client Embed Coderml('config')
call HTML.NOTE: When rml('config') "embedPosition" is "sidebar" this value has no impact.
- roomElementIDThe "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. WhenembedPosition
is set tosidebar
, this value still needs to be present, but you do not need a corresponding div in your markup with that ID. - options:chipOnlineLabel(optional) The online label of the chip that open/closes the sidebar room. Only needed if you are using
embedPosition: 'sidebar'
- options:chipOfflineLabel(optional) The offline label of the chip that open/closes the sidebar room. Only needed if you are using
embedPosition: 'sidebar'
- options:embedPosition
embedPosition
can beinline
orsidebar
.inline
will insert 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 inroomElementID
.sidebar
will tell Roomlio to put the embedded room in the sidebar. By default the "sidebar" version of Roomlio will be closed. You must use our JS API to open/close it, or you can leverage our pre-built "chip" that can open and close the widget without any custom development work.If you choose to use the Roomlio chip to open/close the sidebar widget, you must have a
<div data-rml-chip />
element in your HTML. The<div data-rml-chip />
element will be where the Roomlio chip/button will appear that is used to open and close the sidebar room. - 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:offlineMessageMessage displayed when your widget is turned off.
- options:offlineContactEmailContact email shown when your widget is turned off.
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', }, }, });
- roomElementIDThe "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. WhenembedPosition
is set tosidebar
, this value still needs to be present, but you do not need a corresponding div in your markup with that ID. - options:userIDYour internal user id, or something that uniquely identifies the user to Roomlio
- options:usernameUsername of user, will be shown if no first/last name provided
- options:firstFirst name of user
- options:lastLast name of the user
- options:roomKeyA 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:roomNameDisplay name of the room shown to users in the sidebar of the Roomlio App
- options:traitsTraits 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('open')
Open the room. Only useful if you useembedPosition: 'sidebar'
.rml('open', { roomElementID: 'rml-room-1', // id of room you want to open });
rml('close')
Close the room. Only useful if you useembedPosition: 'sidebar'
.rml('close', { roomElementID: 'rml-room-1', // id of room you want to close });
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; } });
- rml_openedWhen the sidebar room is opened the
rml_opened
event is emitted. Only emits whenrml('config')
hasembedPosition: 'sidebar'
// rml_opened object { type: 'rml_opened', payload: { roomElementID: '<room-element-id>' } }
- rml_closedWhen the sidebar room is closed the
rml_closed
event is emitted. Only emits whenrml('config')
hasembedPosition: 'sidebar'
// rml_closed object { type: 'rml_closed', payload: { roomElementID: '<room-element-id>' } }
- rml_state_changeEmits 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_msgEmits 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_focusWhen 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'; }