Chat API

The Messaging System provides a comprehensive set of endpoints for managing chat rooms and messages within your game. All endpoints require user authentication to ensure proper access control. The system supports real-time communication through WebSocket connections, allowing for instant message delivery and presence updates.

Features

Chat Rooms

• Create new chat rooms
• List available chat rooms
• Get specific chat room details
• Join/leave chat rooms

Messages

• Send messages to chat rooms
• Retrieve message history for a room
• Receive real-time message updates via WebSocket

API Structure

The API is organized into two main sections:

1. Chat Rooms (/rooms/*)

   • GET /rooms - List all available chat rooms
   • POST /rooms - Create a new chat room
   • GET /rooms/:roomId - Get specific chat room details
   • POST /rooms/:roomId/join - Join a chat room
   • POST /rooms/:roomId/leave - Leave a chat room

2. Messages (/rooms/:roomId/messages/*)

   • GET /rooms/:roomId/messages - Get message history for a room
   • POST /rooms/:roomId/messages - Send a new message to the room

WebSocket Events

When connected to the WebSocket server, clients will receive the following events:

• message.new - Emitted when a new message is sent to a room
• message.edit - Emitted when a message is edited
• message.delete - Emitted when a message is deleted
• user.join - Emitted when a user joins a room
• user.leave - Emitted when a user leaves a room

Authentication

All endpoints require:

• User authentication (userAuthentication middleware)
• Game validation (socialGameValidation middleware) for most endpoints

Usage

To use the messaging system, first create a chat room using the POST /rooms endpoint. Once created, users can join the room using the POST /rooms/:roomId/join endpoint. Messages can then be sent and retrieved using the message endpoints. For real-time updates, connect to the WebSocket server to receive message events.

Example flow:

1. Connect to WebSocket server
2. Create a chat room
3. Join the chat room
4. Send messages
5. Receive real-time message updates
6. Retrieve message history
7. Leave the chat room when done

Socket Connection Guide

Overview

This guide explains how to establish and maintain a real-time connection with the chat service using WebSockets. The chat service uses Socket.IO for real-time communication.

Connection Setup

1. Initial Connection

To establish a connection with the chat service, you need to:

1. Connect to the WebSocket server
2. Subscribe to chat rooms using your authentication token

2. Authentication

Before subscribing to rooms, you need to provide your authentication token. This token is used to identify your user session and authorize your connection.

3. Room Subscription

After establishing the connection, you need to emit a 'subscribe-rooms' event with your authentication token to receive real-time updates for your chat rooms.

Implementation Examples

JavaScript/TypeScript (Socket.IO)

// Initialize socket connection
const socket = io('https://socket-svr.openloot.com');

// Subscribe to rooms with authentication token
socket.emit('subscribe-rooms', { token: 'USER_AUTH_TOKEN' });

// Listen for events
socket.on('event-name', (data) => {
  // Handle incoming data
});

Python

import socketio

# Initialize socket client
sio = socketio.Client()

# Connect to server
sio.connect('https://socket-svr.openloot.com')

# Subscribe to rooms
sio.emit('subscribe-rooms', {'token': 'YOUR_AUTH_TOKEN'})

# Listen for events
@sio.on('event-name')
def on_event(data):
    # Handle incoming data
    pass

Unreal Engine (C++)

// Initialize socket connection
FSocketIOClient SocketClient;
SocketClient.Connect("https://socket-svr.openloot.com");

// Subscribe to rooms
TSharedPtr<FJsonObject> AuthData = MakeShared<FJsonObject>();
AuthData->SetStringField("token", "YOUR_AUTH_TOKEN");
SocketClient.Emit("subscribe-rooms", AuthData);

// Listen for events
SocketClient.On("event-name", [](const TSharedPtr<FJsonObject>& Data) {
    // Handle incoming data
});

Events

The chat service may emit various events that your client should handle:

Socket Events Specification

Chat Events

chat.room.created

Emitted when a new chat room is created.

{
  room: {
    id: string;          // UUID of the created room
    type: string;        // Room type (PRIVATE, GROUP, PUBLIC)
    name?: string;       // Room name (for GROUP and PUBLIC rooms)
    members: string[];   // Array of user IDs in the room
    createdAt: string;   // ISO timestamp
  }
}

chat.user.joined

Emitted when a user joins a chat room.

{
  roomId: string;        // UUID of the room
  userId: string;        // UUID of the user who joined
  username: string;      // Username of the user who joined
  joinedAt: string;      // ISO timestamp
}

chat.message.created

Emitted when a new message is created in a chat room.

{
  roomId: string;        // UUID of the room
  message: {
    id: string;          // UUID of the message
    body: string;        // Message content
    userId: string;      // UUID of the sender
    username: string;    // Username of the sender
    createdAt: string;   // ISO timestamp
    metadata?: object;   // Optional message metadata
  }
}

chat.user.left

Emitted when a user leaves a chat room.

{
  roomId: string;        // UUID of the room
  userId: string;        // UUID of the user who left
  username: string;      // Username of the user who left
  leftAt: string;        // ISO timestamp
}

chat.room.closed

Emitted when a chat room is closed.

{
  roomId: string;        // UUID of the closed room
  closedAt: string;      // ISO timestamp
}

Friend Events

social.friend.received

Emitted when a friend request is received.

{
  requestId: string;     // UUID of the friend request
  fromUserId: string;    // UUID of the sender
  fromUsername: string;  // Username of the sender
  createdAt: string;     // ISO timestamp
}

social.friend.accepted

Emitted when a friend request is accepted.

{
  requestId: string;     // UUID of the friend request
  userId: string;        // UUID of the user who accepted
  username: string;      // Username of the user who accepted
  acceptedAt: string;    // ISO timestamp
}

social.friend.removed

Emitted when a friend is removed.

{
  userId: string;        // UUID of the removed friend
  username: string;      // Username of the removed friend
  removedAt: string;     // ISO timestamp
}

Guild Events

social.guild.create

Emitted when a new guild is created.

{
  guild: {
    id: string;          // UUID of the guild
    name: string;        // Guild name
    leader: string;      // UUID of the guild leader
    createdAt: string;   // ISO timestamp
  }
}

social.guild.update

Emitted when guild information is updated.

{
  guildId: string;       // UUID of the guild
  updates: {
    name?: string;       // Updated guild name
    description?: string;// Updated guild description
    image?: string;      // Updated guild image URL
    dailyMessage?: string;// Updated guild daily message
  }
}

social.guild.disband

Emitted when a guild is disbanded.

{
  guildId: string;       // UUID of the disbanded guild
  disbandedAt: string;   // ISO timestamp
}

social.guild.member.update

Emitted when a guild member's information is updated.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the updated member
  updates: {
    rank?: string;       // Updated rank
    permissions?: string[];// Updated permissions
  }
}

social.guild.member.joined

Emitted when a user joins a guild.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the new member
  username: string;      // Username of the new member
  joinedAt: string;      // ISO timestamp
}

social.guild.member.left

Emitted when a user leaves a guild.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the member who left
  username: string;      // Username of the member who left
  leftAt: string;        // ISO timestamp
}

social.guild.member.invite

Emitted when a user is invited to a guild.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the invited user
  username: string;      // Username of the invited user
  invitedBy: string;     // UUID of the user who sent the invite
  invitedAt: string;     // ISO timestamp
}

social.guild.member.decline

Emitted when a guild invite is declined.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the user who declined
  username: string;      // Username of the user who declined
  declinedAt: string;    // ISO timestamp
}

social.guild.member.cancel

Emitted when a guild invite is canceled.

{
  guildId: string;       // UUID of the guild
  userId: string;        // UUID of the user whose invite was canceled
  username: string;      // Username of the user whose invite was canceled
  canceledAt: string;    // ISO timestamp
}

Party Events

social.party.create

Emitted when a new party is created.

{
  party: {
    id: string;          // UUID of the party
    leader: string;      // UUID of the party leader
    createdAt: string;   // ISO timestamp
  }
}

social.party.join

Emitted when a user joins a party.

{
  partyId: string;       // UUID of the party
  userId: string;        // UUID of the new member
  username: string;      // Username of the new member
  joinedAt: string;      // ISO timestamp
}

social.party.leave

Emitted when a user leaves a party.

{
  partyId: string;       // UUID of the party
  userId: string;        // UUID of the member who left
  username: string;      // Username of the member who left
  leftAt: string;        // ISO timestamp
}

social.party.invite

Emitted when a user is invited to a party.

{
  partyId: string;       // UUID of the party
  userId: string;        // UUID of the invited user
  username: string;      // Username of the invited user
  invitedBy: string;     // UUID of the user who sent the invite
  invitedAt: string;     // ISO timestamp
}

social.party.decline

Emitted when a party invite is declined.

{
  partyId: string;       // UUID of the party
  userId: string;        // UUID of the user who declined
  username: string;      // Username of the user who declined
  declinedAt: string;    // ISO timestamp
}

social.party.cancel

Emitted when a party invite is canceled.

{
  partyId: string;       // UUID of the party
  userId: string;        // UUID of the user whose invite was canceled
  username: string;      // Username of the user whose invite was canceled
  canceledAt: string;    // ISO timestamp
}

social.party.update

Emitted when party information is updated.

{
  partyId: string;       // UUID of the party
  updates: {
    status?: string;     // Updated party status
    // Other party-specific updates
  }
}

social.party.disband

Emitted when a party is disbanded.

{
  partyId: string;       // UUID of the disbanded party
  disbandedAt: string;   // ISO timestamp
}

Notes

• All timestamps are in ISO 8601 format
• All IDs are UUIDs
• All events are emitted in real-time as they occur
• Events may include additional metadata specific to the game or application
• Some fields may be optional depending on the context