Skip to main content

​
Messaging System

The Kin Conecta messaging system enables direct, real-time communication between tourists and local guides. Built on a thread-based architecture, it facilitates tour planning, coordination, and relationship building between users.
The messaging system supports text-based communication with read receipts and is designed for both pre-booking inquiries and post-booking coordination.

​
System Overview

The messaging infrastructure uses a thread-based model where conversations are organized into chat threads containing multiple messages.

Chat Threads

Conversations between two users are organized into persistent threads that maintain message history.

Message Types

Support for different message types including text messages with extensibility for future media support.

Read Receipts

Track when messages have been read with timestamp tracking.

Real-time Delivery

Messages are delivered and stored immediately for instant communication.

​
Message Structure

Each message in the system contains the following information: 
{
  "messageId": 1234,
  "threadId": 567,
  "senderUserId": 42,
  "body": "Hola! Estoy interesado en tu tour de gastronomía en CDMX. ¿Tienes disponibilidad para el próximo fin de semana?",
  "messageType": "TEXT",
  "sentAt": "2026-03-10T14:30:00",
  "readAt": "2026-03-10T14:35:00"
}

​
Field Descriptions

Unique identifier for the message. Auto-generated by the system.
Identifier linking the message to a specific conversation thread between two users.
The ID of the user who sent the message (tourist or guide).
The text content of the message. Stored as TEXT type for long messages.
Type of message content. Currently supports:
  • TEXT: Standard text message
  • Future: IMAGE, LOCATION, BOOKING_REQUEST
Timestamp when the message was sent. Automatically recorded on creation.
Timestamp when the message was read by the recipient. null if unread.

​
API Endpoints

The messaging system provides RESTful endpoints for chat operations:

​
Send a Message

POST /messages
Content-Type: application/json

{
  "threadId": 567,
  "senderUserId": 42,
  "body": "Hola! Me interesa tu tour...",
  "messageType": "TEXT"
}
Creates and sends a new message in the specified thread. Response: Returns the created message object with generated messageId and sentAt timestamp.

​
Get Messages by Thread

GET /messages/thread/{threadId}
Retrieves all messages for a specific conversation thread, ordered chronologically. Response: Array of message objects: 
[
  {
    "messageId": 1234,
    "threadId": 567,
    "senderUserId": 42,
    "body": "Message text...",
    "messageType": "TEXT",
    "sentAt": "2026-03-10T14:30:00",
    "readAt": "2026-03-10T14:35:00"
  },
  // ... more messages
]

​
How to Use the Messaging System

1

Initiate Conversation

When a tourist finds a guide they’re interested in (via matching or search), they can initiate a conversation. The system creates a new thread linking the two users.
2

Send Messages

Users send messages through the API or UI, providing the thread ID, their user ID, and message content.
3

Receive & Read

Recipients retrieve messages from the thread. When a message is displayed to the recipient, the readAt timestamp is updated.
4

Continue Conversation

Users continue exchanging messages in the same thread, maintaining conversation history and context.

​
Implementation Details

The messaging system is implemented with the following components:

​
Controller

socialNetwork/src/main/java/org/generation/socialNetwork/messenger/controller/ChatMessageController.java
Handles HTTP requests for sending and retrieving messages.

​
Model

socialNetwork/src/main/java/org/generation/socialNetwork/messenger/model/ChatMessage.java
Defines the message entity structure and database mapping.

​
Database Table

Messages are stored in the chat_messages table with the following schema: 
CREATE TABLE chat_messages (
  message_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  thread_id BIGINT NOT NULL,
  sender_user_id BIGINT NOT NULL,
  body TEXT,
  message_type ENUM('TEXT', ...) NOT NULL,
  sent_at DATETIME NOT NULL,
  read_at DATETIME NULL,
  INDEX idx_thread (thread_id),
  INDEX idx_sender (sender_user_id)
);
The thread_id index ensures fast retrieval of conversation history, while the sender_user_id index enables efficient queries for user-specific message operations.

​
Message Types

The system uses an enum to define message types: 
public enum MessageType {
    TEXT,
    // Future extensions:
    // IMAGE,
    // LOCATION,
    // BOOKING_REQUEST,
    // SYSTEM_NOTIFICATION
}
Currently, only TEXT messages are fully implemented, but the architecture supports future extensions.

​
Use Cases

Pre-Booking Inquiries

Tourists ask questions about tour details, availability, customization options, and pricing before making a booking.

Tour Coordination

After booking, users coordinate meeting times, locations, and any special requests or changes.

Relationship Building

Ongoing communication helps build trust and rapport between tourists and guides.

Post-Tour Follow-up

Users can thank each other, share photos, or discuss future tour opportunities.

​
User Experience Flow

​
For Tourists

  1. Discover a Guide: Find a compatible guide through matching or search
  2. Start Conversation: Click “Message” to open a chat thread
  3. Ask Questions: Inquire about tours, availability, customization
  4. Coordinate Details: Finalize meeting points, times, and special requests
  5. Stay Connected: Continue communication before, during, and after the tour

​
For Guides

  1. Receive Inquiry: Get notified when a tourist sends a message
  2. Respond Promptly: Answer questions about tours and availability
  3. Provide Details: Share additional information, photos, or recommendations
  4. Confirm Bookings: Coordinate logistics and confirm tour details
  5. Build Relationships: Maintain communication for potential repeat business
Message threads should be linked to user accounts. Ensure proper authentication and authorization to prevent unauthorized access to private conversations.

​
Best Practices

Response Time

Quick responses improve user experience. Guides should aim to respond within 24 hours.

Professional Tone

Maintain professional, friendly communication to build trust and credibility.

Clear Information

Provide specific details about tours, pricing, and logistics to avoid confusion.

Safety & Privacy

Avoid sharing sensitive personal information until booking is confirmed.

​
Future Enhancements

Planned improvements to the messaging system:
  • Real-time Notifications: Push notifications for new messages
  • Media Support: Share images, videos, and location pins
  • Typing Indicators: Show when the other user is typing
  • Message Reactions: Quick emoji reactions to messages
  • Voice Messages: Audio message support
  • Translation: Automatic translation for cross-language communication
  • Booking Integration: Create booking requests directly from chat
  • Archive & Search: Search message history and archive old conversations

Related Documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us