Roomlio Web API

INTRODUCTION

You can use the web API to access Roomlio data. The Roomlio API is more of an RPC style, instead of REST. Don't let this scare you if you are used to REST style APIs. It is simple to understand, just know that all requests are made via a POST request. Using the navigation on the left, you'll find details for each endpoint and type of object used in the API.

The base URL to send all API requests is https://api.roomlio.com/rpc. HTTPS is required for all API requests.

The Roomlio Web API follows RPC conventions. Requests are POSTs and will return 200. Request and response bodies are encoded as JSON.

AUTHENTICATION

Requests use the HTTP Authorization header to both authenticate and authorize requests. The Roomlio API key you receive when creating an API key under Roomlio settings can then be used as the Bearer token.

PAGINATION

Endpoints which return a list of objects use pagination. Pagination allows an integration to request a part of the list, receiving an array of results and a nextCursor in the response. The integration can use the startCursor or since parameters in another request to receive the next part of the list. Using this technique, the integration can continue to make requests to receive the whole list (or just the parts the integration needs).

ERRORS

Responses from the API use HTTP response codes are used to indicate general classes of success and error. Error responses contain more detail about the error in the response body, in the "code" and "message" properties.

METHODS

We only have one method call at the moment but we are planning on adding more in the near future. Please reach out if you would like us to add another method.

RoomHistory()

PARAMS

roomID string

The id of the Roomlio room (e.g. rm_bvr0h6tnf4q1u52mfit0) of which you want to retrieve messages. Use this or roomKey below.
roomKey string

(optionally used instead of roomID above) Your generated room identifier that you will provide when registering the users to chat.
limit int

(optional) Limit the number of messages returned. Default is 100. Maximum is 1000.
startCursor string

(optional) The message id from which to start fetching. You can use nextCursor for this value which is provided in the response.
since string

(optional) ISO 8601 formated timestamp that can be used instead of startCursor if you want to fetch messages starting at a certain date/time.

RESPONSE

messages array

An array of messages.
hasMore boolean

Will return true if there are more messages in the room to return.
nextCursor string

The message id to use for startCursor in your next fetch if hasMore returns true.

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/RoomHistory' \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"roomID":"rm_bvr0h6tnf4q1u52mfit0", "limit": 2}'

// Response
{
  "messages": [
    {
      "id": "msg_bvr0ngdnf4q1u52mfj0g",
      "userID": "usr_bvr0h6tnf4q1u52mfisg",
      "visibility": "",
      "username": "",
      "first": "",
      "last": "",
      "userType": "admin", // 'admin', 'member', 'embed', or 'embed_insecure'
      "body": "Hi! I have a questions.",
      "messageType": "user", // 'user', 'offline', 'system'
      "links": [], // an array of image link objects {id: "lnk_c2r833ua0brilr22jt60", type: "image", url: "https://img_url.png"}
      "roomID": "rm_bvr0h6tnf4q1u52mfit0",
      "roomName": "",
      "createdAt": "2021-01-06T19:13:05Z",
      "editedAt": "0001-01-01T00:00:00Z" // if '0001-01-01T00:00:00Z' is returned that means the message has not been edited
    },
    ...
  ],
  "hasMore": true,
  "nextCursor": "msg_1e1gcpgdp9e0z"
}

UserRooms()

PARAMS

userID string

The userID of the user for whom you want to get a list of rooms. This userID is your unique identifier for your users. It should be unique across all of your users. The userID you use here corresponds to the userID you send in the rml('register') or rml('registerSecure') call to register your users so they can chat in embedded chat rooms. It will also be the same userID you send if you are creating users using our optional UserCreate web API endpoint.

RESPONSE

rooms array

An array of rooms for the corresponding userID.

// POST Request
$ curl "https://api.roomlio.com/rpc/WebAPI/UserRooms" \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"userID":"<your users unique identifier>"}'

// Response
{
  "rooms": [
    {
      "id": "rm_ces6uig7t2un74c3l4j0",
      "name": "support",
      "type": "open",
      "createMethod": "embed",
      "widgetID": "wgt_bvu70q5nf4q1u52mft4g",
      "allowEmbedding": true,
      "createdAt": "2023-01-06T12:58:18Z",
      "archivedAt": "0001-01-01T00:00:00Z",
      "roomKey": "paddysPub101",
      "markerMessageID": "msg_1fhjkat6al78e" // last message seen by the user.
    }
    ...
  ]
}

UserUnreadMessages()

PARAMS

userID string

The userID of the user for whom you want to get a list of unread messages. This userID is your unique identifier for your users. It should be unique across all of your users. The userID you use here corresponds to the userID you send in the rml('register') or rml('registerSecure') call to register your users so they can chat in embedded chat rooms. It will also be the same userID you send if you are creating users using our optional UserCreate web API endpoint.

RESPONSE

rooms array

An array of rooms for the corresponding userID that have unread messages. Each room array will have an array of unread messages.
NOTE: Only rooms with unread messages will be returned.

// POST Request
$ curl "https://api.roomlio.com/rpc/WebAPI/UserUnreadMessages" \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"userID":"<your users unique identifier>"}'

// Response
{
  "rooms": [
    {
      "id": "rm_ces6uig7t2un74c3l4j0",
      "name": "paddysPub",
      "messages": [
        {
          "id": "msg_1fk1ke9am14ea",
          "userID": "<message user's id>",
          "visibility": "",
          "username": "dennisR",
          "isModerator": true,
          "first": "Dennis",
          "last": "Reynolds",
          "userType": "admin", // 'admin', 'member', 'embed', or 'embed_insecure'
          "userRole": "",
          "body": "BE GONE!",
          "messageType": "user", // 'user', 'offline', 'system'
          "links": [], // an array of image link objects {id: "lnk_c2r833ua0brilr22jt60", type: "image", url: "https://img_url.png"}
          "roomID": "rm_ces6uig7t2un74c3l4j0",
          "roomName": "paddysPub",
          "createdAt": "2023-02-06T13:33:54Z",
          "editedAt": "0001-01-01T00:00:00Z" // if '0001-01-01T00:00:00Z' is returned that means the message has not been edited
        }
        ...
      ]
    }
    ...
  ]
}

PARAMS

widgetID string

The id of the widget (e.g. wgt_bvr0h6tnf4q1u52mfit0) that was used to create the rooms you want a list of.

RESPONSE

rooms array

An array of rooms. Each room will also have an array of users that belong to the room.

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/WidgetRooms' \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"widgetID":"wgt_bvr0h6tnf4q1u52mfit0"}'

// Response
"rooms": [
    {
      "id": "rm_cdhag4k3c37km765fmo0",
      "name": "Support",
      "type": "open",
      "createMethod": "embed",
      "allowEmbedding": true,
      "createdAt": "2022-11-02T12:25:38Z",
      "archivedAt": "0001-01-01T00:00:00Z",
      "roomKey": "support-one-niner",
      "users": [
        {
          "id": "usr_cdhag4k3c37km765fmng",
          "email": "<users email>",
          "displayName": "dReynolds",
          "first": "",
          "last": "",
          "customerUserID": "sweetD123456789",
          "avatar": "",
          "userType": "embed_insecure",
          "isModerator": false,
          "role": "",
          "isBanned": false,
          "createdAt": "2022-11-02T12:25:38Z",
          "updatedAt": "2022-11-04T13:33:41Z",
          "sendUnreadNotificationsEmail": false
        }
        ...
      ]
    },
    ...
  ]

PARAMS

name string

The name of the Roomlio room.
state string

(optional) The online state of the widget. Used if you want to use the offline feature. Sometimes you might want all rooms created with this widget to start offline. Default is "on".

embedPosition

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

greetingMessageUsername string

(optional) Username of the greeting message the user will see when they first enter the room. Default is "Support".
greetingMessage string

(optional) Greeting message the user will see when they first enter the room. Default is ":wave: Question? Just type it below and we are online and ready to answer".
offlineGreetingMessage

(optional) Text shown above the offline message form telling the user that you're offline.
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. An example of the offlineMessageFields object can be found in the rml('config') code block.
offlineSendButton

(optional) Text of the offline message form submit button.
offlineThankYou

(optional) Message displayed in the room after a visitor submits the offline form.
offlineForwardingEmail

(optional) Email to forward offline messages.
offlineSubject

(optional) Subject of the email sent to the offlineForwardingEmail.
selfIdentifyGreetingMsg

(optional) Text shown above the self/user identify form telling the user about the form.
selfIdentifyFormFields

(optional) You can change the labels of the self/user identify 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 selfIdentifyFormFields in the rml('config') call will turn on the form and override all fields set in your widget's "User Identify Form" tab in the app settings. An example of the selfIdentifyFormFields object can be found in the rml('config') code block. displayName, first, last, email, opt1, and opt2 are the only fields that can be used. You can change the label to fit your scenario.

NOTE: selfIdentifyFormFields is only for the insecure register call, rml('register'), and will be ignored if used with rml('registerSecure').

NOTE: opt1 and opt2 will be displayed in the room's user info sidebar.

NOTE: Do not supply any user options (i.e. userID, displayName, traits, etc) in the rml('register') API call if using self identify since the register call, which is called everytime the page loads, will override any matching fields provided in the self identify form.
selfIdentifyButtonLabel

(optional) Text of the self/user identify form submit button.
collapsedMode

(optional) 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.
collapsedModeOnlineLabel

(optional) The online label of the collapsed room. Not applicable when the embedPosition is inline or collapsedMode is set to hidden.
collapsedModeOfflineLabel

(optional) The offline label of the collapsed room. Not applicable when the embedPosition is inline or collapsedMode is set to hidden.

RESPONSE

widget object

Newly created widget

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/WidgetCreate' \
  -H "Authorization: Bearer <your secret key>" \
  -H 'content-type: application/json' \
  --data '{"name": "Support", "state": "on", "embedPosition": "inline", "greetingMessageUsername": "Support", "greetingMessage":":wave: Question? Just type it below and we are online and ready to answer", "offlineSendButton": "Send", "offlineGreetingMessage":"Hi, we aren\'t 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\": true, \"enabled\": true}, \"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false}, \"opt2\": {\"label\": \"Address\", \"required\": false, \"enabled\": false}, \"opt3\": {\"label\": \"\", \"required\": false, \"enabled\": false}}", "offlineThankYou":"Thank you for sending your message! We will get back to you shortly!", "offlineSubject":"New Roomlio Offline Message", "offlineForwardingEmail":"support@test.com", "selfIdentifyFormFields":"{\"displayName\": {\"label\": \"Display Name\", \"required\": true, \"enabled\": true}, \"first\": {\"label\": \"First Name\", \"required\": false, \"enabled\": false}, \"last\": {\"label\": \"Last Name\", \"required\": false, \"enabled\": false}, \"email\": {\"label\": \"Email\", \"required\": false, \"enabled\": false}, \"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false}, \"opt2\": {\"label\": \"Custom Field\", \"required\": false, \"enabled\": false}}", "selfIdentifyFormEnabled": false, "selfIdentifyButtonLabel":"Start Chatting", "selfIdentifyGreetingMsg":"Add your info to chat", "collapsedMode": "tab", "collapsedModeOnlineLabel": "Question? Chat with us now.", "collapsedModeOfflineLabel": "Contact Us"}'

// Response
{
  "widget":
    {
      "id": "wgt_cbokh6mg26u5c5116c5g",
      "name": "Support",
      "inviteGroupID": "ig_cdmheu4bibhd6p0mqrr0", // use inviteGroupID to invite other users to rooms that are created with this widget
      "state": "on",
      // offline settings
      "offlineMessageFields": "{\"message\": {\"label\": \"Message\", \"required\": true, \"enabled\": true},\"email\": {\"label\": \"Email\", \"required\": true, \"enabled\": true},\"name\": {\"label\": \"Name\", \"required\": true, \"enabled\": true},\"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false},\"opt2\": {\"label\": \"Address\", \"required\": false, \"enabled\": false},\"opt3\": {\"label\": \"\", \"required\": false, \"enabled\": false}\n}",
      "offlineSendButton": "Send",
      "offlineThankYou": "Thank you for sending your message! We will get back to you shortly!",
      "offlineSubject": "New Roomlio Offline Message",
      "offlineForwardingEmail": "<email to forward to>",
      "offlineGreetingMessage": "Hi, we aren't around right now. Leave us a message and we will get back to you.",
      // self identify settings
      "selfIdentifyFormFields": "{\"displayName\": {\"label\": \"Display Name\", \"required\": true, \"enabled\": true},\"first\": {\"label\": \"First Name\", \"required\": false, \"enabled\": false},\"last\": {\"label\": \"Last Name\", \"required\": false, \"enabled\": false},\"email\": {\"label\": \"Email\", \"required\": false, \"enabled\": false},\"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false},\"opt2\": {\"label\": \"Custom Field\", \"required\": false, \"enabled\": false}\n}",
      "selfIdentifyFormEnabled": false,
      "selfIdentifyButtonLabel": "Start Chatting",
      "selfIdentifyGreetingMsg": "Add your info to chat",
      // greeting message settings
      "greetingMessageUsername": "Support",
      "greetingMessage": ":wave: Question? Just type it below and we are online and ready to answer",
      // collapsed mode settings
      "collapsedMode": "tab",
      "collapsedModeOnlineLabel": "Question? Chat with us now.",
      "collapsedModeOfflineLabel": "Contact Us",
    },
}

Widgets()

NO PARAMS

RESPONSE

widgets array

An array of widgets

// POST Request
$ curl "https://api.roomlio.com/rpc/WebAPI/Widgets" \
  -H "Authorization: Bearer <your_secret_key>" \
  -H "content-type: application/json" \
  -X POST

// Response
{
  "widgets": [
    {
      "id": "wgt_cbokh6mg26u5c5116c5g",
      "name": "support",
      "state": "on",
      "offlineMessageFields": "{\"message\": {\"label\": \"Message\", \"required\": true, \"enabled\": true},\"email\": {\"label\": \"Email\", \"required\": true, \"enabled\": true},\"name\": {\"label\": \"Name\", \"required\": true, \"enabled\": true},\"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false},\"opt2\": {\"label\": \"Address\", \"required\": false, \"enabled\": false},\"opt3\": {\"label\": \"\", \"required\": false, \"enabled\": false}\n}",
      "offlineSendButton": "Send",
      "offlineThankYou": "Thank you for sending your message! We will get back to you shortly!",
      "offlineSubject": "New Roomlio Offline Message",
      "offlineForwardingEmail": "",
      "offlineGreetingMessage": "Hi, we aren't around right now. Leave us a message and we will get back to you.",
      "selfIdentifyFormFields": "{\"displayName\": {\"label\": \"Display Name\", \"required\": true, \"enabled\": true},\"first\": {\"label\": \"First Name\", \"required\": false, \"enabled\": false},\"last\": {\"label\": \"Last Name\", \"required\": false, \"enabled\": false},\"email\": {\"label\": \"Email\", \"required\": false, \"enabled\": false},\"opt1\": {\"label\": \"Company\", \"required\": false, \"enabled\": false},\"opt2\": {\"label\": \"Custom Field\", \"required\": false, \"enabled\": false}\n}",
      "selfIdentifyFormEnabled": false,
      "selfIdentifyButtonLabel": "Start Chatting",
      "selfIdentifyGreetingMsg": "Add your info to chat",
      "greetingMessageUsername": "Support",
      "greetingMessage": ":wave: Question? Just type it below and we are online and ready to answer",
      "collapsedMode": "tab",
      "collapsedModeOnlineLabel": "Question? Chat with us now.",
      "collapsedModeOfflineLabel": "Contact Us",
    },
    ...
  ],
}

PARAMS

widgetID string

The id of the widget (e.g. wgt_bvr0h6tnf4q1u52mfit0) of which you want get the widget operators.
NOTE: Each widget has a group of widget operators who will be automatically invited when a room is created by this widgetID.

RESPONSE

users array

An array of users assigned to this widget. These users will be automatically added to new rooms created by the widgetID passed in.

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/WidgetOperators' \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"widgetID":"wgt_bvr0h6tnf4q1u52mfit0"'

// Response
{
  "users": [
    {
      "userID": "usr_c93hu4qsahsgvke95bk0",
      "username": "johnGlenn",
      "first": "john",
      "last": "glenn",
      "type": "member",
      "email": "<users email>",
      "avatar": "",
      "currentRoomID": "rm_bsm7jt3d0cvlisdir1i0",
      "isModerator": false,
      "sendUnreadNotificationsEmail": false,
      "role": "",
      "__rmlRef": "usr_cg0h3belrtrrkiojb2lg"
    }
    ...
  ],
}

PARAMS

widgetID string

The id of the widget (e.g. wgt_bvr0h6tnf4q1u52mfit0) to which you want to add a user.
NOTE: each widget has a group of users that will be invited to the room created by this widget
userIDs array

An array of userID strings to be added to this widget.

RESPONSE

users array

An array of users assigned to this widget. These users will be automatically added to new rooms created by the widgetID passed in.

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/WidgetOperatorsAdd' \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"widgetID":"wgt_bvr0h6tnf4q1u52mfit0", "userIDs":["usr_c1vdds9p1lt9pfu3tfi0", "usr_bq5iele29tquq0pic5og"]}'

// Response
"users": [
    {
      "userID":"usr_bm2co21n0omvns6b65qg",
      "username":"jSmith",
      "first":"Julie",
      "last":"Smith",
      "type":"admin",
      "email":"<users email>",
      "avatar":"",
      "currentRoomID":"rm_cecc61i73pdsqalpp1ug",
      "isModerator":true,
      "sendUnreadNotificationsEmail":true,
      "role":"",
      "__rmlRef": "usr_cg0h3belrtrrkiojb2lg"
    },
    ...
  ]

PARAMS

widgetID string

The id of the widget (e.g. wgt_bvr0h6tnf4q1u52mfit0) to which you want to remove a user.
NOTE: each widget has a group of users that will be invited to the room created by this widget
userIDs array

An array of userID strings to be removed from this widget.

RESPONSE

users array

An array of users assigned to this widget. These users will be automatically added to new rooms created by the widgetID passed in.

// POST Request
$ curl 'https://api.roomlio.com/rpc/WebAPI/WidgetOperatorsRemove' \
  -H "Authorization: Bearer <your_secret_key>" \
  -H 'content-type: application/json' \
  --data '{"widgetID":"wgt_bvr0h6tnf4q1u52mfit0", "userIDs":["usr_c1vdds9p1lt9pfu3tfi0", "usr_bq5iele29tquq0pic5og"]}'

// Response
"users": [
    {
      "userID":"usr_bm2co21n0omvns6b65qg",
      "username":"jSmith",
      "first":"Julie",
      "last":"Smith",
      "type":"admin",
      "email":"<users email>",
      "avatar":"",
      "currentRoomID":"rm_cecc61i73pdsqalpp1ug",
      "isModerator":true,
      "sendUnreadNotificationsEmail":true,
      "role":"",
      "__rmlRef": "usr_cg0h3belrtrrkiojb2lg"
    },
    ...
  ]