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.dev/rpc/RoomlioService/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"
}