Virola Web API - Messages

GET /api/v1/rooms/${roomId}/messages

Purpose

Retrieves a list of messages from a specific chat room, with support for pagination and directional loading.

Authentication

  • Required: Secure, HTTP-only session cookie
  • Unauthorized access returns a 401 error.

Request

  • Method: GET

  • URL Format: /api/v1/rooms/${roomId}/messages?cursor=2000129&limit=100&direction=backward

    • roomId: The unique identifier of the chat room to fetch messages from.

  • Query Parameters:

    • cursor: The message ID to start from.
    • limit: Maximum number of messages to return.
    • direction:
      • "backward" for older messages
      • "forward" for newer messages

  • Headers: None required

  • Cookies: Must include a valid session cookie

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200,
  "messages": [
    {
      "attachments": [
        {
          "attachmentId": 13,
          "attachmentState": "ReadyForDownloadFromServerToClient",
          "createdUtc": 0,
          "fileChecksum": "74578eba4b0802bd3c1f0adee5985eb5933a4aad",
          "fileName": "Screenshot.png",
          "fileSize": 63560,
          "hasThumbnail": true,
          "lastModifiedUtc": 1753209786659,
          "roomId": 2,
          "textMessageId": 2000124
        }
      ],
      "commentCount": 0,
      "createdUtc": 1753207692547,
      "lastEditedUtc": 1753207692547,
      "lastModifiedUtc": 1753359160687,
      "markupType": "TextPlain",
      "messageId": 2000124,
      "messageType": "Regular",
      "parentMessageId": 0,
      "priority": "Normal",
      "roomId": 2,
      "text": "Test message with attachment",
      "userId": 1
    },
    {
      "attachments": [],
      "commentCount": 0,
      "createdUtc": 1753210377178,
      "lastEditedUtc": 1753210377178,
      "lastModifiedUtc": 1753210404075,
      "markupType": "TextPlain",
      "messageId": 2000129,
      "messageType": "Regular",
      "parentMessageId": 0,
      "priority": "Normal",
      "roomId": 2,
      "text": "Test message",
      "userId": 3
    }
  ],
  "roomId": 2
}

Explanation:

  • messages: An array of message objects

    • messageId: Unique identifier for the message

    • parentMessageId: ID of the parent message if this is a comment (0 if not a comment)

    • userId: ID of the user who sent the message

    • roomId: ID of the room the message was sent in

    • text: The content of the message

    • createdUtc: Timestamp when the message was created

    • lastModifiedUtc: Timestamp when the message was last modified

    • lastEditedUtc: Timestamp when the message was last edited

    • markupType: Type of markup used

      • Possible values:
        • TextPlain
        • TextHtml
        • TextMarkdown
        • TextCode
        • TextLatex

    • messageType: Type of message

      • Possible values:
        • Regular
        • Issue
        • Meeting

    • priority: Priority of the message

      • Possible values:
        • Blocker
        • Critical
        • High
        • Normal
        • Low
        • Trivial

    • commentCount: Number of comments on this message

    • attachments: Array of attachment objects (if any)

      • attachmentId: Unique identifier for the attachment

      • fileName: Name of the file

      • fileSize: Size of the file in bytes

      • fileChecksum: Checksum for file integrity

      • hasThumbnail: Indicates if a thumbnail is available

      • attachmentState: Current state of the attachment

        • Possible states:
          • Initial,
          • ChecksumCalculationOnClientSideInProgress,
          • ChecksumCalculationOnClientSideFailed,
          • UploadFromClientToServerInProgress,
          • UploadFromClientToServerFailed,
          • ChecksumVerificationOnServerSideInProgress,
          • ChecksumVerificationOnServerSideMismatch,
          • ChecksumVerificationOnServerSideFailed,
          • ReadyForDownloadFromServerToClient

      • createdUtc, lastModifiedUtc: Timestamps for the attachment

      • textMessageId: ID of the message this attachment belongs to

      • roomId: ID of the room the attachment belongs to

  • roomId: Unique identifier for the chat room

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

  • errorText: Contains a description of the failure
  • httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

Usage Notes

  • This endpoint is typically used in chat applications to display messages in a room, allowing efficiently load messages while users scroll through the conversation history.
  • Use message ID as the cursor parameter to control where to start loading messages. If not specified, it defaults to the first or last message in the room, depending on the direction parameter. If direction is "backward", it will load older messages starting from the most recent message. If "forward", it will load newer messages starting from the oldest message.
  • The direction parameter allows you to specify whether to load older messages ("backward") or newer messages ("forward") beginning from the specified cursor (message ID). If not specified, the default is to load newer messages.
  • The limit parameter allows you to control how many messages are returned in a single request. If not specified, all messages according to cursor and direction parameters will be returned.
  • Messages are returned in chronological order based on their messageId.

All available Web API calls