Chattiq - Socket Events/Listeners

Chat Gateway - Real-time Communication

Socket URL: https://stage-api.chattiq.com
📅 13 October, 2026
🔗 connection
Handles user socket connection, sets user online status, joins personal room, and broadcasts online status to all other users.
📋 Client Request Parameters Required
Client sends during handshake
Parameter name: auth
"auth": { "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
⚠️ This will throw an UnauthorizedException if token is wrong or expired.
📤 Server sends to all users (broadcast) Receive
Event: status:online
Broadcasts the connecting user's online status to all other connected users in the network (not sent back to the connecting user itself).
{ "userId": 1, "uId": "U1811afaa1762944980", "isOnline": true, "lastSeen": null }
📝 Workflow: User initiates connection → Server authenticates via handshake with token → Sets user online status → Joins personal socket room → Broadcasts online status event to all other connected users → Connection established
📥 join:chat
User joins a specific chat room, marks all messages as seen, and updates unread message count for both sender and receiver.
📋 Client Request Parameters Required
Client sends
{ "chatUniqueId": "Cf87bef2f1763356475" (Required) }
📤 Server sends to both participants Receive
Event: unread:updated
Sent to both sender and receiver to update the unread message count after joining chat.
{ "chatUniqueId": "Cf87bef2f1763356475", "unreadCount": 0 }
📝 Workflow: User joins chat room → All messages in room marked as seen → Unread count set to 0 → "unread:updated" event emitted to both participants
💬 private:message
Sends a private message in a chat room (text, story reply, shared post, or shared profile). Saves message to database and emits confirmation to sender, message to receiver, chat list updates to both users, and a push notification to the receiver.
📋 Client Request Parameters Required
Client sends
{ "chatUniqueId": "Cf87bef2f1763356475", (Required) "message": "Hello, how are you?" (Optional caption for shared types; may be empty string) "messageType": "text" (Optional - Default: text. Options: text, storyReply, sharedPost, sharedProfile) "storyUniqueId": "S1234567890" (Required if messageType is storyReply) "postUniqueId": "P1234567890" (Required if messageType is sharedPost) "profileUId": "U1234567890" (Required if messageType is sharedProfile) }
For sharedPost / sharedProfile, message:delivered and message:received include a post object (with postMedia) or sharedProfile user object instead of story. Push notification type is sharedPost or sharedProfile.
📤 Server sends to sender Send
Event: message:delivered
Confirms to the message sender that their message was successfully delivered and saved on the server.
{ "messageUniqueId": "Mc26e06381763969287", "sender": { "id": 1, "uId": "U90b050251763356077", "role": "user", "adminRole": null, "userName": "demo", "firstName": "demo", "lastName": "demo", "email": "demo@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "4334565676", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763356077 }, "receiver": { "id": 2, "uId": "Ueebd29621763545130", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "message": "???", "messageType": "storyReply", "story": { "storyUniqueId": "STf77a7cf81763616542", "media": "https://devcenter1.assets.heroku.com/article-images/726-imported-1443570257-726-imported-1443554724-sample.jpg", "mediaThumbnail": "https://devcenter1.assets.heroku.com/article-images/726-imported-1443570257-726-imported-1443554724-sample.jpg", "mediaType": "image", "user": { "id": 6, "uId": "Ueebd29621763545430", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "isViewed": false, "viewCount": 0, "likeCount": 0, "createdAt": 1764307742 }, "isSeen": false, "createdAt": 1763969287 }
📥 Server sends to receiver Receive
Event: message:received
Delivers the message to the receiver with full message data and unread status (initially marked as unread).
{ "messageUniqueId": "Mc26e06381763969287", "sender": { "id": 1, "uId": "U90b050251763356077", "role": "user", "adminRole": null, "userName": "demo", "firstName": "demo", "lastName": "demo", "email": "demo@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "4334565676", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763356077 }, "receiver": { "id": 2, "uId": "Ueebd29621763545130", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "message": "???", "messageType": "storyReply", "story": { "storyUniqueId": "STf77a7cf81763616542", "media": "https://devcenter1.assets.heroku.com/article-images/726-imported-1443570257-726-imported-1443554724-sample.jpg", "mediaThumbnail": "https://devcenter1.assets.heroku.com/article-images/726-imported-1443570257-726-imported-1443554724-sample.jpg", "mediaType": "image", "user": { "id": 6, "uId": "Ueebd29621763545430", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "isViewed": false, "viewCount": 0, "likeCount": 0, "createdAt": 1764307742 }, "isSeen": false, "createdAt": 1763969287 }
📤 Server sends to both users Receive
Event: last:message
Emitted to both sender and receiver to update their chat list with the new message as the last message and current unread count.
{ "chatUniqueId": "Cab1ac37f1763631258", "participant": { "id": 6, "uId": "Ueebd29621763545430", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "lastMessage": "???", "lastMessageAt": 1763969287, "messageType": "text", "unreadCount": 0, "createdAt": 1763976721 }
📝 Workflow: Client sends message with chatUniqueId → Server validates message (and linked story, post, or profile when applicable) → Saves to database with full metadata → Transforms ChatMessage entity → Transforms Chat entity → Emits "message:delivered" to sender → Emits "message:received" to receiver → Emits "last:message" to both users to update chat lists → Sends push notification (type varies by messageType)
📨 bulk:share
Shares a post or profile with multiple users in one request. Chat rooms are created or reused automatically (no chatUniqueId in the payload). For each successful recipient, the server runs the same delivery flow as private:message.
📋 Client Request Parameters Required
Client sends
{ "messageType": "sharedPost", (Required - sharedPost or sharedProfile) "userIds": ["U1234567890", "U0987654321"], (Required - recipient uId array; duplicates and self are skipped) "message": "Check this out", (Optional caption) "postUniqueId": "P1234567890", (Required if messageType is sharedPost) "mediaId": 1 (Optional - stored on the message as mediaId when messageType is sharedPost) "profileUId": "U1234567890" (Required if messageType is sharedProfile) }
📤 Server sends per successful recipient Receive
Same as private:message
For each recipient: message:delivered (sender), message:received (recipient), last:message (both), plus push notification with type sharedPost or sharedProfile.
📤 Server sends to sender when finished Send
Event: bulk:share:completed
Summary after all share attempts. Sent to the sender's personal room (uId).
{ "messageType": "sharedPost", "succeeded": ["U1234567890", "U0987654321"], "failed": [ { "uId": "U0000000000", "reason": "User not found" } ] }
📝 Workflow: Client emits bulk:share → Server resolves recipients in batch → Creates or finds chats → Inserts messages → For each success, emits the same events as private:message → Emits bulk:share:completed to sender with succeeded and failed lists
✅ message:seen
Marks a specific message as seen by the receiver. Updates message status in database and sends read receipt to sender.
📋 Client Request Parameters Required
Client sends
{ "chatUniqueId": "Cf87bef2f1763356475", (Required) "messageUniqueId": "M410c89611763362890" (Required) }
📤 Server sends to sender (read receipt) Send
Event: message:seen
Notifies the sender that their message was read by the receiver (read receipt with message marked as seen).
{ "messageUniqueId": "Mc26e06381763969287", "sender": { "id": 1, "uId": "U90b050251763356077", "role": "user", "adminRole": null, "userName": "demo", "firstName": "demo", "lastName": "demo", "email": "demo@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "4334565676", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763356077 }, "receiver": { "id": 2, "uId": "Ueebd29621763545130", "role": "user", "adminRole": null, "userName": "testing", "firstName": "User2", "lastName": "testing", "email": "user2@gmail.com", "countryCode": "+91", "isoCode": "in", "phone": "7046629027", "profilePic": "https://example.com/profile.jpg", "providerType": null, "isDisclaimer": true, "isHideAge": true, "isShowGenderInBio": true, "isShowSexualOrientationInBio": true, "isBlocked": false, "distance": 5.5, "isNotificationOn": true, "dateOfBirth": "1993-04-20", "bio": "test bio", "photos": null, "reason": null, "schoolDetails": "Test School", "schoolDescription": "Test School Description", "interestedIn": "men", "latitude": null, "longitude": null, "timezone": null, "otherGender": "Agender", "steps": 1, "isOnline": false, "createdAt": 1763545430 }, "message": "???", "isSeen": true, "createdAt": 1763969287 }
📥 Server sends to receiver (confirmation) Receive
Event: unread:updated
Updates the receiver's unread message count after marking message as seen.
{ "chatUniqueId": "Cf87bef2f1763356475", "unreadCount": 0 }
📝 Workflow: Client marks message as seen → Server updates message status in database → Records seen timestamp → Emits "message:seen" to sender with read receipt → Emits "unread:updated" to receiver with updated count
⌨️ typing
Real-time typing indicator. Broadcasts when a user is typing to the specific receiver in a chat room.
📋 Client Request Parameters Required
Client sends
{ "chatUniqueId": "Cf87bef2f1763356475", (Required) "receiverUId": "U9a55e4921762517559", (Required) "isTyping": true (Optional - Default: true) }
📥 Server sends to specific receiver (real-time) Receive
Event: typing
Real-time notification that sender is typing. Only sent to the specified receiver (not broadcast to all users).
{ "chatUniqueId": "Cf87bef2f1763356475", "senderUId": "U1811afaa1762944980", "receiverUId": "U9a55e4921762517559", "isTyping": true }
📝 Details: Set isTyping: true when user starts typing. Set isTyping: false to indicate user stopped typing. Event is emitted only to the specified receiver, not broadcast. Typically sent continuously while user is composing to show live typing indicator on receiver's UI.
📤 leave:chat
User leaves the chat room. Removes the user from the room socket and clears typing indicator.
📋 Client Request Parameters Required
Client sends
{ "chatUniqueId": "Cf87bef2f1763356475" (Required) }
📝 Action: User initiates leave → Server removes socket from room → Typing indicator cleared → User no longer receives room-specific events
🔌 disconnection
Handles user socket disconnection. Sets user offline status and broadcasts offline status with last seen timestamp to all other connected users.
📤 Server sends to all users (broadcast) Receive
Event: status:offline
Broadcasts offline status to all other connected users with the exact timestamp of when the user was last seen.
{ "userId": 1, "uId": "U1811afaa1762944980", "isOnline": false, "lastSeen": 1763476185 }
📝 Workflow: User disconnects (browser close/network loss/logout) → Server sets offline status → Records last seen timestamp → Removes user from all chat rooms → Broadcasts "status:offline" event to all other connected users → Socket connection closed
🚫 user:blocked
Notifies a user when they are blocked or unblocked by another user. This event is triggered via API call when a user blocks/unblocks another user.
🔄 Server action triggered from API API Endpoint
When block/unblock API is called
User A calls the block/unblock API for User B → Server processes the action
📥 Server sends to blocked user only Receive
Event: user:blocked
Sent to the blocked user's personal socket room (identified by their uId) to notify them of the block/unblock status change.
{ "blockedBy": "U90b050251763356077", "isBlockedMe": true }
Note: When isBlockedMe is true = user has been blocked
When isBlockedMe is false = user has been unblocked
📝 Workflow: User A calls block/unblock API for User B → Server processes block/unblock action → Server calls emitUserBlocked() method → Event emitted to User B's socket room (uId) → User B receives notification about block status change. The blocked user can use this to update their UI (disable messaging, show blocked status, etc.). Only the blocked user receives this notification, not the blocker.
🟢 status:online (Check User Status)
Allows a user to manually check whether another user is currently online or offline. This event is typically used when opening a chat screen or profile to show real-time online status and last seen information.
📋 Client Request Parameters Required
Client sends
{ "senderUId": "U90b050251763356077", (Required) "receiverUId": "Ueebd29621763545130" (Required) }
senderUId = user who wants to check the status
receiverUId = user whose status is being checked
📥 Server sends to sender only Receive
Event: status:online
Server checks the receiver's current online status from the database and sends the result only to the requesting user (sender).
{ "userId": 2, "uId": "Ueebd29621763545130", "isOnline": false, "lastSeen": 1763476185 }
📝 Workflow: Sender emits status:online with senderUId and receiverUId → Server checks receiver's online status from database → Server emits status:online response only to the sender → Sender updates UI (Online / Offline / Last Seen).
🚫 user:blocked
Checks if a user is blocked by another user.
📋 Client Request Parameters Required
Client sends
{ "senderUId": "U90b050251763356077", (Required) "receiverUId": "Ueebd29621763545130" (Required) }
📥 Server sends to sender only Receive
Event: user:blocked
Sent to the sender's personal socket room (identified by their uId) to notify them of the block status.
{ "blockedBy": "Ueebd29621763545130", "isBlockedMe": false }
📝 Workflow: User A calls user:blocked event with senderUId and receiverUId → Server checks if user is blocked → Server emits user:blocked response only to the sender → Sender updates UI (block status).
🗑️ user:deleted
Notifies all users when a user is deleted. This event is triggered via API call when a user is deleted.
📤 Server sends to all users (broadcast) Receive
Event: user:deleted
Broadcasts delete user event to all other connected users.
{ "deletedUserUId": "U90b050251763356077" "isDeleted": true }
📝 Workflow: User is deleted → Server calls emitDeleteUser() method → Event emitted to all connected users → All users receive notification about user deletion.
🗑️ user:deleted (Check Delete Status)
Checks if a user is deleted.
📋 Client Request Parameters Required
Client sends
{ "senderUId": "U90b050251763356077", (Required) "receiverUId": "Ueebd29621763545130" (Required) }
📥 Server sends to sender only Receive
Event: user:deleted
Sent to the sender's personal socket room (identified by their uId) to notify them of the delete status.
{ "deletedUserUId": "Ueebd29621763545130", "isDeleted": true }
📝 Workflow: User A calls user:deleted event with senderUId and receiverUId → Server checks if user is deleted → Server emits user:deleted response only to the sender → Sender updates UI (delete status).