Skip to main content
The Chat Server API includes a messaging system built around conversations with multiple participants. While the core entities are defined, the full implementation including WebSocket support is still in development.

​
Conversation entity

Conversations represent message threads between users. The entity structure is currently defined but not fully implemented:
Conversation.java
//@Getter
//@Setter
//@Entity
//@Table
//public class Conversation {
//    //TODO [Reverse Engineering] generate columns from DB
//}
The Conversation entity is currently commented out and marked for reverse engineering from the database schema. This indicates the messaging feature is planned but not yet available in the API.

​
Expected structure

Based on common patterns and the existing ConversationParticipant entity, a conversation will likely include:

Unique identifier

UUID primary key for each conversation

Participants list

One-to-many relationship with ConversationParticipant

Messages

Collection of messages in the conversation

Metadata

Creation timestamp, last message time, etc.

​
ConversationParticipant entity

The participant entity links users to conversations with a unique constraint preventing duplicate memberships:
ConversationParticipant.java
//@Entity
//@Table(name = "conversation_participants", 
//       uniqueConstraints = @UniqueConstraint(columnNames = {"conversation_id", "user_id"}))
//public class ConversationParticipant {
//    @Id
//    @GeneratedValue(strategy = GenerationType.UUID)
//    private String id;
//
//    @ManyToOne
//    @JoinColumn(name = "conversation_id", nullable = false)
//    private Conversation conversation;
//}

​
Participant model features

The @UniqueConstraint on conversation_id and user_id ensures:
  • Each user can only be added to a conversation once
  • No duplicate participant records
  • Database-level integrity enforcement
@UniqueConstraint(columnNames = {"conversation_id", "user_id"})
While the entity is defined, it’s currently commented out pending full implementation. The structure suggests support for both direct messages and group conversations.

​
WebSocket support for real-time messaging

Real-time messaging will be implemented using WebSocket connections. While not yet active in the codebase, this is a planned feature for instant message delivery.

​
Expected WebSocket architecture

1

Establish connection

Client connects to WebSocket endpoint with JWT token authentication:
const ws = new WebSocket('wss://api.example.com/ws');
ws.send(JSON.stringify({
  type: 'auth',
  token: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
}));
2

Subscribe to conversations

After authentication, subscribe to specific conversation channels:
ws.send(JSON.stringify({
  type: 'subscribe',
  conversationId: 'uuid-of-conversation'
}));
3

Send messages

Send messages through the WebSocket connection:
ws.send(JSON.stringify({
  type: 'message',
  conversationId: 'uuid-of-conversation',
  content: 'Hello, world!'
}));
4

Receive messages

Listen for incoming messages from other participants:
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'message') {
    console.log(`New message: ${data.content}`);
  }
};

​
WebSocket message types

The messaging system will likely support these message types:
Initial handshake to verify JWT token and establish user identity:
{
  "type": "auth",
  "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Response:
{
  "type": "auth_success",
  "userId": "uuid-of-user"
}
Text messages sent between participants:
{
  "type": "message",
  "conversationId": "uuid",
  "content": "Message text",
  "timestamp": "2026-03-04T12:00:00Z"
}
Real-time notifications when users are typing:
{
  "type": "typing",
  "conversationId": "uuid",
  "userId": "uuid",
  "isTyping": true
}
Track when messages are read by participants:
{
  "type": "read",
  "conversationId": "uuid",
  "messageId": "uuid",
  "userId": "uuid"
}

​
Relationship to friendships

Messaging will integrate with the relationship system to ensure users can only message their friends.

​
Access control

Before allowing users to create conversations or send messages, the API will verify: 
// Verify users have an ACCEPTED relationship
Relationship relationship = relationshipRepository
    .findRelationshipByUserAndOtherUser(userId, otherUserId)
    .orElseThrow(() -> new UnauthorizedException());

if (relationship.getStatus() != RelationshipStatus.ACCEPTED) {
    throw new UnauthorizedException("Can only message friends");
}
Only users with an ACCEPTED relationship status can start conversations or send messages to each other. See the Relationships documentation for details on friend requests.

​
Message permissions

Requirements:
  • Both users must have RelationshipStatus.ACCEPTED
  • Either user can initiate the conversation
  • Both users have equal send/receive permissions
// Create conversation between friends
Conversation directMessage = new Conversation();
directMessage.addParticipant(user1);
directMessage.addParticipant(user2);

​
Message persistence

While WebSocket provides real-time delivery, messages will also be persisted to the database for:
  • Message history retrieval
  • Offline message delivery
  • Search functionality
  • Compliance and moderation

​
Expected Message entity

@Entity(name = "messages")
public class Message {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private String id;
    
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "conversation_id", nullable = false)
    private Conversation conversation;
    
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "sender_id", nullable = false)
    private User sender;
    
    @Column(nullable = false, length = 2000)
    private String content;
    
    @Column(nullable = false)
    private LocalDateTime sentAt;
    
    @Column
    private LocalDateTime editedAt;
    
    @Column(nullable = false)
    private boolean deleted = false;
}

​
Current implementation status

The messaging system is currently not implemented. The entity classes are defined but commented out, indicating they are planned for a future release.

​
What’s available now

  • Entity structure definitions (commented out)
  • Database constraints for participants
  • Relationship system for access control

​
What’s coming

  • Active Conversation and ConversationParticipant entities
  • Message entity for storing chat history
  • WebSocket endpoint for real-time messaging
  • REST endpoints for conversation management
  • Message pagination and search
  • Read receipts and typing indicators
Check the repository’s issue tracker or roadmap for updates on messaging feature development. The authentication and relationship systems are already complete and ready to support messaging once implemented.

Build docs developers (and LLMs) love

Get started for freeTalk to us