Events API Documentation

The /api/v1/events endpoint provides a real-time event stream used by clients to receive notifications from the server. This WebSocket connection complements the REST API by pushing updates instantly without polling.

Endpoints: ws(s)://your-server.com/api/v1/events

Overview

The Events WebSocket delivers real-time notifications about activity in chat rooms and user sessions. After establishing a WebSocket connection, the client automatically begins receiving events relevant to the authenticated user, such as new messages, message edits, read receipts, room updates, etc.

The server ensures that each connected client only receives events for the rooms and resources they have permission to access.

Event Types:

• TextMessagesCreated: A new text message(s) has been created in a room.
• TextMessagesUpdated: An existing text message(s) has been updated.
• TextMessageDeleted: An existing text message has been deleted.
• RoomCreated: A new room has been created.
• RoomUpdated: An existing room has been updated.
• RoomDeleted: An existing room has been deleted.
• Related API

---

TextMessagesCreated Event

Purpose

Notify clients when new text messages are created in a room.

Event Payload

{
    "type": "TextMessagesCreated",
    "data": {
        "messages": [
            {
                "messageId": 2000124,
                "messageType": "Regular",
                "roomId": 2,
                "text": "Test message with attachment",
                "userId": 1,
                ... other message fields ...
            }
        ]
    }
}

Explanation:

• eventType: The type of event being sent (TextMessagesCreated)
• data: Contains the event-specific data
  • messages: An array of message objects that were created

Usage Notes:

• Message objects include all standard message fields as defined in the Messages API documentation.

---

TextMessagesUpdated Event

Purpose

Notify clients when existing text messages are updated in a room.

Event Payload

{
    "type": "TextMessagesUpdated",
    "data": {
        "messages": [
            {
                "messageId": 2000124,
                "messageType": "Regular",
                "roomId": 2,
                "text": "Updated message text",
                "userId": 1,
                ... other message fields ...
            }
        ]
    }
}

Explanation:

• type: The type of event being sent (TextMessagesUpdated)
• data: Contains the event-specific data
  • messages: An array of message objects that were updated

Usage Notes

• Message objects include all standard message fields as defined in the Messages API documentation.

---

TextMessageDeleted Event

Purpose

Notify clients when existing text messages are deleted from a room.

Event Payload

{
    "type": "TextMessageDeleted",
    "data": {
        "parentMessageId": 2000124,
        "roomId": 2,
        "messageId": 2000125
    }
}

Explanation:

• type: The type of event being sent (TextMessageDeleted)
• data: Contains the event-specific data
  • parentMessageId: ID of the parent message if message was a comment
  • roomId: ID of the room the message was deleted from
  • messageId: ID of the deleted message

---

RoomCreated Event

Purpose

Notify clients when a new room is created.

Event Payload

{
    "type": "RoomCreated",
    "data": {
        "room": {
            "roomId": 2,
            "name": "New Room",
            ... other room fields ...
        }
    }
}

Explanation:

• type: The type of event being sent (RoomCreated)
• data: Contains the event-specific data
  • room: The room object that was created

Usage Notes

• Room object include all standard room fields as defined in the Rooms API documentation.

---

RoomUpdated Event

Purpose

Notify clients when an existing room is updated.

Event Payload

{
    "type": "RoomUpdated",
    "data": {
        "room": {
            "roomId": 2,
            "name": "Updated Room Name",
            ... other room fields ...
        }
    }
}

Explanation:

• type: The type of event being sent (RoomUpdated)
• data: Contains the event-specific data
  • room: The room object that was updated

Usage Notes

• Room object include all standard room fields as defined in the Rooms API documentation.

---

RoomDeleted Event

Purpose

Notify clients when an existing room is deleted.

Event Payload

{
    "type": "RoomDeleted",
    "data": {
        "roomId": 2
    }
}

Explanation:

• type: The type of event being sent (RoomDeleted)
• data: Contains the event-specific data
  • roomId: ID of the room that was deleted

Related API

• Messages API - retrieve and send messages
• Comments API - retrieve and send comments on messages
• Rooms API - retrieve room information and avatars

All available Web API calls

• Authentication with token – suitable for individual requests
• Authentication with a username and password – suitable for maintaining a session to send multiple requests
• Login with username and password – suitable for individual requests
• Logout the current user – terminate the current session
• Getting user status – check the current user's authentication and session status
• Users API – retrieve user information
• Rooms API – retrieve room information
• Messages API – retrieve and send messages
• Comments API – retrieve and send comments on messages
• Attachments API – manage message attachments
• Events API – receive real-time updates about changes on the server
• Permissions API – retrieve user permissions in rooms
• Server Health API – check the health status of the Virola Server