Chat Service Developer API Documentation
Version: 2.0
Last Updated: 2025-02-10
Author: Nozimjon Nabiev
1. Overview
The Chat Service is a real‑time and RESTful API designed to handle chat conversations, order
status updates, support ticket creation, and online user tracking. The system is built on Spring
Boot, uses Hibernate for ORM, Redis for caching and messaging, and Socket.IO for real‑time
communication.
2. User Types
The system distinguishes several user types, each with different permissions and access
scopes:
ADMIN:
Full access to all chats, orders, and users. Can view and manage every aspect of the
system.
MODERATOR:
Similar to Admins, with permissions to moderate content and oversee chats.
MERCHANT:
Represents a merchant; they view chats where the chat’s merchantId matches theirs. For
support chats, branch and order details are not present.
BRANCH_MANAGER:
Manages a branch; can access chats associated with their branch (chats where branchId
matches).
CASHIER:
Similar to Branch Managers, with access limited to branch‑related chats.
CUSTOMER:
End users who see only the chats in which they participate. Their support chats are those
that lack branch and merchant information.
SERVER:
System‑level users that typically trigger backend operations (e.g., new order processing).
They have limited or system‑specific privileges.
3. REST API Endpoints
3.1 Get All Chats
Endpoint:
GET /api/v2/chats
Description:
Retrieves a paginated list of chats for the current user. The results are filtered based on the
user’s role and a boolean parameter ( support ) that determines whether to return support chats
or regular chats.
Query Parameters:
page (Integer, default: 1): The page number (1-indexed).
limit (Integer, default: 10): The number of chats per page.
support (Boolean, default: false):
true : Returns support chats (e.g., chats where orderId is null).
false : Returns non‑support chats.
Sample Request:
GET /api/v2/chats?page=1&limit=10&support=false HTTP/1.1
Authorization: Bearer <token>
Sample Success Response:
{
"data" : [ {
"id" : "b4c6dfe8-3748-4b4e-b78e-c8dbf20c4c38",
"orderId" : "9f46b696-0f79-4fb9-8090-2cfde0dd18a0",
"merchantId" : "64e1029b-94ae-440b-8daf-c25ffd5943a9",
"branchId" : "74e1029b-94ae-440b-8daf-c25ffd5943a9",
"updatedAt" : "2025-02-07T06:59:17.043665",
"customerId" : "e2465aeb-d154-4651-bf8c-725858d85548",
"lastMessages" : {
"id" : "4d9c3070-769c-4156-98fb-a3430f06d8b0",
"content" : "9f46b696-0f79-4fb9-8090-2cfde0dd18a0",
"userId" : "a2465aeb-d154-4651-bf8c-725858d85548",
"chatId" : "b4c6dfe8-3748-4b4e-b78e-c8dbf20c4c38",
"type" : "ORDER",
"isRead" : null,
"createdAt" : "2025-02-07T06:59:17.042244",
"image" : null,
"orderId" : "9f46b696-0f79-4fb9-8090-2cfde0dd18a0"
},
"unreadCount" : 0
}, {
"id" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"merchantId" : null,
"branchId" : "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"updatedAt" : "2025-01-05T00:56:00.180635",
"customerId" : "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"lastMessages" : {
"id" : "9f2e07d0-f769-4e43-9769-5c9a64af8280",
"content" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "ACCEPTED_CUSTOMER",
"isRead" : null,
"createdAt" : "2025-02-10T01:49:02.826567",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63"
},
"unreadCount" : 0
} ],
"total" : 2,
"limit" : 20,
"page" : 1,
"pages" : 1
}
Sample Error Response:
{
"status": "INTERNAL_SERVER_ERROR",
"timeStamp": "20250210 01:04:04",
"message": "Something went wrong while fetching chats."
}
Important:
isRead property is set to null if message is not sent by the user that sent the request for
getting all chats. But if it is current user's message it is value is either false or true indicating
it is read by other user's or not.
3.2 Get Chat by ID
Endpoint:
GET /api/v2/chats/{chatId}
Description:
Fetches detailed information for a specific chat, including the participants (customer, branch
manager, merchant).
Path Parameter:
chatId (UUID): The unique identifier of the chat.
Sample Request:
GET /api/v2/chats/f654c1cd-55e9-46de-ac15-b3c0c2c35382 HTTP/1.1
Authorization: Bearer <token>
Sample Success Response:
{
"id": "f654c1cd-55e9-46de-ac15-b3c0c2c35382",
"orderId": "0c91f3bf-597b-4917-b1a5-d6d8f7815114",
"merchantId": "53e0f7b8-f414-4c57-4395-764a8ef0e8cd",
"branchId": "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"updatedAt": "2025-02-01T01:42:27.477807",
"users": [
{
"id": "3668eb70-a337-4e1f-bb65-9e3f7a23d276",
"lastSeen": "2025-01-29T22:40:09.863704",
"branchId": null,
"merchantId": null,
"userType": "CUSTOMER"
},
{
"id": "5768eb70-a337-4e1f-bb65-9e3f7a23d276",
"lastSeen": "2025-01-29T22:40:09.863704",
"branchId": "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId": null,
"userType": "BRANCH_MANAGER"
},
{
"id": "1438eb70-a337-4e1f-bb65-9e3f7a23d276",
"lastSeen": "2025-01-29T22:40:09.863704",
"branchId": "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId": "0b575adc-df04-415e-858c-ff0426aaf168",
"userType": "MERCHANT"
}
]
}
Sample Error Response (Resource Not Found):
{
"status": "NOT_FOUND",
"timeStamp": "20250210 01:04:04",
"message": "Chat not found for ID: f654c1cd-55e9-46de-ac15-b3c0c2c35382"
}
3.3 Get Chat by Order ID
Endpoint:
GET /api/v2/chats/by-order/{orderId}
Description:
Retrieves the chat details associated with the specified order ID.
Path Parameter:
orderId (UUID): The unique order identifier.
Sample Request:
GET /api/v2/chats/by-order/0c91f3bf-597b-4917-b1a5-d6d8f7815114 HTTP/1.1
Authorization: Bearer <token>
Sample Success Response:
{
"id": "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"orderId": "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"merchantId": null,
"branchId": "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"updatedAt": "2025-01-05T00:56:00.180635",
"users": [
{
"id": "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"lastSeen": "2025-02-09T22:39:01.382535",
"branchId": null,
"merchantId": null,
"userType": "CUSTOMER"
},
{
"id": "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"lastSeen": "2025-02-08T21:49:04.277486",
"branchId": "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId": "0b575adc-df04-415e-858c-ff0426aaf168",
"userType": "BRANCH_MANAGER"
}
]
}
Sample Error Response (Resource Not Found):
{
"status": "NOT_FOUND",
"timeStamp": "20250210 01:04:04",
"message": "Chat not found for ID: 7c79f6fe-d002-4961-a6e7-b00476f551c2"
}
3.4 Delete Chat
Endpoint:
DELETE /api/v2/chats/{chatId}
Description:
Deletes a chat specified by its chat ID. Only ADMIN and MODERATOR users have permission
to perform this action.
Path Parameter:
chatId (UUID): The unique chat identifier.
Sample Request:
DELETE /api/v2/chats/f654c1cd-55e9-46de-ac15-b3c0c2c35382 HTTP/1.1
Authorization: Bearer <token>
Sample Success Response:
HTTP 204 No Content
Sample Error Response (Access Denied):
{
"status": "FORBIDDEN",
"timeStamp": "20250210 01:04:04",
"message": "Access denied: You are not allowed to delete this chat."
}
3.5 Get Chat Messages
Endpoint:
GET /api/v2/chats/{chatId}/messages
Description:
Retrieves a paginated list of messages for the given chat.
Path Parameter:
chatId (UUID): The unique chat identifier.
Query Parameters:
page (Integer, default: 1): The page number (1-indexed).
limit (Integer, default: 50): The number of messages per page.
Sample Request:
GET /api/v2/chats/01f6d5ee-f0f5-4e59-a6c1-cd5daa287f72/messages?page=1&limit=50
HTTP/1.1
Authorization: Bearer <token>
Sample Success Response:
{
{
"data" : [ {
"id" : "9f2e07d0-f769-4e43-9769-5c9a64af8280",
"content" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "ACCEPTED_CUSTOMER",
"createdAt" : "2025-02-10T01:49:02.826567",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"user" : {
"id" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"lastSeen" : "2025-02-09T22:37:16.364636",
"branchId" : null,
"merchantId" : null,
"userType" : "ADMIN"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ ]
}, {
"id" : "aa4edf3a-4da7-4beb-8f58-7552ffc08332",
"content" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "ACCEPTED_MERCHANT",
"createdAt" : "2025-02-10T01:48:18.102136",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"user" : {
"id" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"lastSeen" : "2025-02-09T22:37:16.364636",
"branchId" : null,
"merchantId" : null,
"userType" : "ADMIN"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ ]
}, {
"id" : "6a4d416b-3170-4b87-aa13-9f8c029fc85f",
"content" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "ACCEPTED_MERCHANT",
"createdAt" : "2025-02-10T01:38:48.563941",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"user" : {
"id" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"lastSeen" : "2025-02-09T22:37:16.364636",
"branchId" : null,
"merchantId" : null,
"userType" : "ADMIN"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ ]
}, {
"id" : "8b86ea05-0774-4e3c-bb95-d477c5f4da46",
"content" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "ACCEPTED_MERCHANT",
"createdAt" : "2025-02-10T01:38:48.563941",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"user" : {
"id" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"lastSeen" : "2025-02-09T22:37:16.364636",
"branchId" : null,
"merchantId" : null,
"userType" : "ADMIN"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ ]
}, {
"id" : "93a3fed6-7a23-4834-bfce-f741b10fb4bd",
"content" : "Edited message",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "TEXT",
"createdAt" : "2025-02-08T03:28:03.129888",
"image" : null,
"orderId" : null,
"user" : {
"id" : "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"lastSeen" : "2025-02-08T21:49:04.277486",
"branchId" : "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId" : "0b575adc-df04-415e-858c-ff0426aaf168",
"userType" : "BRANCH_MANAGER"
},
"isEdited" : true,
"repliedToId" : "a80c41da-a0cc-452f-b1d4-aa7e90b7797f",
"repliesCount" : null,
"readBy" : [ {
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"readTime" : "2025-02-10T01:04:49.347899"
} ]
}, {
"id" : "a80c41da-a0cc-452f-b1d4-aa7e90b7797f",
"content" : "New message 711111",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "TEXT",
"createdAt" : "2025-02-07T06:05:48.732816",
"image" : null,
"orderId" : "a2334911-51eb-44ad-9eb3-c4be1432aa63",
"user" : {
"id" : "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"lastSeen" : "2025-02-09T22:39:01.382535",
"branchId" : null,
"merchantId" : null,
"userType" : "CUSTOMER"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : 1,
"readBy" : [ {
"userId" : "f6750646-a998-4e72-b75d-61aef2714cbd",
"readTime" : "2025-02-07T06:10:59.099726"
}, {
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"readTime" : "2025-02-10T01:04:49.347899"
}, {
"userId" : "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"readTime" : "2025-02-08T03:19:13.758712"
} ]
}, {
"id" : "a838d3d5-d928-40b7-beb6-2a5f7297b583",
"content" : "New message 7774000",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "TEXT",
"createdAt" : "2025-02-07T05:54:25.547363",
"image" : null,
"orderId" : null,
"user" : {
"id" : "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"lastSeen" : "2025-02-08T21:49:04.277486",
"branchId" : "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId" : "0b575adc-df04-415e-858c-ff0426aaf168",
"userType" : "BRANCH_MANAGER"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ {
"userId" : "f6750646-a998-4e72-b75d-61aef2714cbd",
"readTime" : "2025-02-07T06:10:59.099726"
}, {
"userId" : "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"readTime" : "2025-02-07T06:06:23.492398"
}, {
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"readTime" : "2025-02-10T01:04:49.347899"
} ]
}, {
"id" : "1af6d988-26b2-4f92-9582-f5ce273face9",
"content" : "New message 7777",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "TEXT",
"createdAt" : "2025-02-07T05:19:36.667944",
"image" : null,
"orderId" : null,
"user" : {
"id" : "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"lastSeen" : "2025-02-08T21:49:04.277486",
"branchId" : "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId" : "0b575adc-df04-415e-858c-ff0426aaf168",
"userType" : "BRANCH_MANAGER"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ {
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"readTime" : "2025-02-10T01:04:49.347899"
}, {
"userId" : "f6750646-a998-4e72-b75d-61aef2714cbd",
"readTime" : "2025-02-07T06:10:59.099726"
}, {
"userId" : "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"readTime" : "2025-02-07T05:33:19.869076"
} ]
}, {
"id" : "7cae52f9-c253-4e08-a1c5-9657d60a91ad",
"content" : "New Test",
"chatId" : "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type" : "TEXT",
"createdAt" : "2025-02-01T02:37:09.888484",
"image" : null,
"orderId" : null,
"user" : {
"id" : "5acededa-39e8-4693-85fd-4b3bc9df2c1d",
"lastSeen" : "2025-02-08T21:49:04.277486",
"branchId" : "59e7f8b8-f414-4c57-8395-764a8ef0e8cd",
"merchantId" : "0b575adc-df04-415e-858c-ff0426aaf168",
"userType" : "BRANCH_MANAGER"
},
"isEdited" : false,
"repliedToId" : null,
"repliesCount" : null,
"readBy" : [ {
"userId" : "0c5144a9-42e3-472e-a05b-f0d00dd2c704",
"readTime" : "2025-02-10T01:04:49.347899"
}, {
"userId" : "f6750646-a998-4e72-b75d-61aef2714cbd",
"readTime" : "2025-02-07T06:10:59.099726"
}, {
"userId" : "cdf5e57c-9fd8-4e3c-9be3-3052a0cc54d5",
"readTime" : "2025-02-01T02:38:47.637918"
} ]
} ],
"total" : 39,
"limit" : 9,
"page" : 1,
"pages" : 4
}
Sample Error Response:
{
"status": "NOT_FOUND",
"timeStamp": "20250210 01:04:04",
"message": "Chat not found with id: 01f6d5ee-f0f5-4e59-a6c1-cd5daa287f72"
}
4. Socket.IO (WebSocket) Events
Real‑time interactions are handled via Socket.IO. Each event has defined payloads and
standardized success/error responses.
4.1 new-message Event
Direction: Client → Server
Description:
Sent by a client when posting a new message. The server processes the message, stores
it, and broadcasts it to relevant chat rooms.
Payload (NewMessagePayload):
chatId: UUID (identifier for the chat)
type: String (e.g., TEXT, IMAGE, ORDER, CONFIRMATION)
content: String (message text)
image: String (URL or image reference; optional)
orderId: UUID (if applicable)
repliedToMessageId: UUID (optional, if this is a reply)
Sample Request Body:
{
"chatId": "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"type":"TEXT",
"content": "New message",
"orderId":"a2334911-51eb-44ad-9eb3-c4be1432aa63",
"image":"8a44d34911-51eb-44ad-9eb3-c4be1432aa63",
"repliedToMessageId":"c4be1432aa63-cdf5e57c-9fd8-4e3c-9be3"
}
Success Response:
Acknowledgment event with a payload indicating success, for example:
{
"success": true,
"status": 200
}
Error Response:
If an error occurs (e.g., missing session, invalid data), the server emits an “error” event:
{
"success": false,
"status": 500,
"message": "Error processing NEW_MESSAGE event.",
"error": "Internal Server Error"
}
4.2 edit-message Event
Direction: Client → Server
Description:
Triggered when a client edits a previously sent message. The server updates the message
and broadcasts the update.
Payload (EditMessagePayload):
messageId: UUID (identifier of the message to be edited)
chatId: UUID (chat identifier)
content: String (updated message content)
Sample Request Body:
{
"chatId": "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"content": "Edited message",
"messageId":"a2334911-51eb-44ad-9eb3-c4be1432aa63"
}
Success Response:
Acknowledgment with a success message:
{
"success": true,
"status": 200
}
Error Response:
{
"success": false,
"status": 403,
"message": "Not authorized to edit messages.",
"error": "Forbidden"
}
4.3 read Event
Direction: Client → Server
Description:
Emitted when a client marks messages as read. The server updates the database and
notifies relevant clients.
Payload (ReadPayload):
chatId: UUID
Sample Request Body:
{
"chatId": "7c79f6fe-d002-4961-a6e7-b00476f551c2"
}
Success Response:
{
"success": true,
"status": 200
}
Error Response:
{
"success": false,
"status": 500,
"message": "Error processing READ event.",
"error": "Internal Server Error"
}
4.4 get-online Event
Direction: Client → Server
Description:
When a client requests the list of online users, the server determines allowed user IDs
(based on the current user’s role and database queries) and checks Redis for their online
status using pipelining. The result excludes the requesting user's ID.
Payload (GetOnlinePayload):
* userId: UUID (sender's identifier)
Sample Request Body:
{
"userId": "2c79f6fe-d042-4961-a6e7-b00476f551c1",
}
Success Response:
{
"success": true,
"status": 200,
"data": ["user-id-1", "user-id-2", "user-id-3"]
}
Error Response:
{
"success": false,
"status": 500,
"message": "Error retrieving online users.",
"error": "Internal Server Error"
}
4.5 order-update Event
Direction: Client → Server
Description:
Emitted when an order update occurs (e.g., order status changes). The server processes
the update and broadcasts the event to relevant chat rooms.
Payload (OrderUpdatePayload):
orderId: UUID
branchId: UUID
type: String order status (e.g., ACCEPTED_MERCHANT, ACCEPTED_CUSTOMER
and etc..)
cancelReason: String (only required for DECLINED_MERCHANT AND
DECLINED_CUSTOMER)
Sample Request Body
{
"chatId": "7c79f6fe-d002-4961-a6e7-b00476f551c2",
"orderId":"a2334911-51eb-44ad-9eb3-c4be1432aa63",
"type": "ACCEPTED_MERCHANT", // DECLINED_MERCHANT, ACCEPTED_CUSTOMER,
DECLINED_CUSTOMER
"cancelReason": "Cancelation reason" // only required for DECLINED_MERCHANT
AND DECLINED_CUSTOMER
}
Success Response:
{
"success": true,
"status": 200
}
Error Response:
{
"success": false,
"status": 500,
"message": "Error processing order update.",
"error": "Internal Server Error"
}
7. Global Exception Handling
All REST endpoints use a global exception handler (via @ControllerAdvice ) that intercepts
exceptions and returns a standardized error response. The key exception types are:
AccessDeniedException:
HTTP Status: 403 Forbidden
Sample Error Response:
{
"status": "FORBIDDEN",
"timeStamp": "20250210 01:04:04",
"message": "Access denied: You are not allowed to perform this action."
}
NotAcceptableRecordException:
HTTP Status: 400 Bad Request
Sample Error Response:
{
"status": "BAD_REQUEST",
"timeStamp": "20250210 01:04:04",
"message": "Customer order id, status or token is null!"
}
ResourceNotFoundException:
HTTP Status: 404 Not Found
Sample Error Response:
{
"status": "NOT_FOUND",
"timeStamp": "20250210 01:04:04",
"message": "Chat not found for ID: f654c1cd-55e9-46de-ac15-b3c0c2c35382"
}
InternalServerException:
HTTP Status: 500 Internal Server Error
Sample Error Response:
{
"status": "INTERNAL_SERVER_ERROR",
"timeStamp": "20250210 01:04:04",
"message": "Something went wrong :("
}
The error response format is consistent across all endpoints and events, ensuring that
developers can reliably handle errors.
This documentation provides a clear, detailed guide for both frontend and backend developers
to interact with the Chat Service. It covers REST endpoints, real‑time Socket.IO events (with
both success and error responses), user roles, and global exception handling—all aimed at
ensuring a consistent and production‑ready integration experience.
