Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/khushboodaryani/Chat-App/llms.txt

Use this file to discover all available pages before exploring further.

The Messages API provides two endpoints that cover the full messaging lifecycle: fetching the history of an existing conversation and sending a new message to another user. Every action is scoped to the authenticated user — the server derives the sender’s identity from the JWT cookie, so the client never needs to pass a sender ID explicitly. Messages are persisted to MongoDB and, when the recipient is currently connected, delivered in real time over Socket.io.
Both endpoints are protected by the protectRoute middleware. You must have a valid jwt cookie (set by signup or login) before calling either route. Requests without a cookie receive a 401 Unauthorized response.

​
GET /api/messages/:id

Retrieves the full conversation history between the authenticated user and another user identified by :id. The server looks up a Conversation document whose participants array contains both user IDs and returns the populated messages array. If no conversation has been started between the two users yet, the endpoint returns an empty array rather than a 404.

​
Path parameters

​
id
string
required
The MongoDB ObjectId (24-character hex string) of the other user in the conversation — i.e., the person you want to read messages with. This is not the conversation ID.

​
Response — 200 OK

Returns an array of Message objects in chronological order. Returns [] when no conversation exists yet — this is not an error condition.
​
_id
string
The MongoDB ObjectId of the individual message document.
​
senderId
string
The MongoDB ObjectId of the user who sent this message.
​
receiverId
string
The MongoDB ObjectId of the user who received this message.
​
message
string
The plain-text content of the message.
​
createdAt
string
ISO 8601 timestamp of when the message was created, added automatically by Mongoose’s timestamps option.
​
updatedAt
string
ISO 8601 timestamp of the last update to this document, added automatically by Mongoose’s timestamps option.
200 Response — conversation with one message
[
  {
    "_id": "665a3f8c1d2e4b0023cd7ef1",
    "senderId": "664f1c2e8b3a4c0012ef9abc",
    "receiverId": "664f1c2e8b3a4c0012ef9def",
    "message": "Hey, are you free to chat?",
    "createdAt": "2024-06-01T10:23:08.000Z",
    "updatedAt": "2024-06-01T10:23:08.000Z"
  }
]
200 Response — no conversation yet
[]

​
Error responses

HTTP Statuserror valueCause
401"Unauthorized - No Token Provided"JWT cookie is absent
401"Unauthorized - Invalid Token"JWT signature verification failed
404"User not found"Decoded JWT refers to a deleted user
500"Internal server error"Unexpected server-side exception

​
POST /api/messages/send/:id

Sends a new message to the user identified by :id. The server resolves the sender from the JWT cookie, locates or creates a Conversation document for the pair, persists the new Message document, and then checks whether the receiver has an active Socket.io connection. If they do, the message is emitted immediately as a newMessage event so the recipient’s UI updates in real time without polling.

​
Path parameters

​
id
string
required
The MongoDB ObjectId of the receiver — the user you are sending this message to.

​
Request body

​
message
string
required
The plain-text content of the message to send. Must be a non-empty string.
Request body example
{
  "message": "Hey, are you free to chat?"
}

​
Response — 201 Created

Returns the newly created Message document.
​
_id
string
The MongoDB ObjectId of the newly created message.
​
senderId
string
The MongoDB ObjectId of the authenticated user who sent the message.
​
receiverId
string
The MongoDB ObjectId of the user the message was sent to (matches :id in the path).
​
message
string
The plain-text content that was sent.
​
createdAt
string
ISO 8601 timestamp of when the message document was created.
​
updatedAt
string
ISO 8601 timestamp of the last update to the message document.
201 Response
{
  "_id": "665a3f8c1d2e4b0023cd7ef1",
  "senderId": "664f1c2e8b3a4c0012ef9abc",
  "receiverId": "664f1c2e8b3a4c0012ef9def",
  "message": "Hey, are you free to chat?",
  "createdAt": "2024-06-01T10:23:08.000Z",
  "updatedAt": "2024-06-01T10:23:08.000Z"
}

​
Error responses

HTTP Statuserror valueCause
401"Unauthorized - No Token Provided"JWT cookie is absent
401"Unauthorized - Invalid Token"JWT signature verification failed
404"User not found"Decoded JWT refers to a deleted user
500"Internal server error"Unexpected server-side exception
Socket.io delivery is best-effort. If the receiver is offline at send time, the newMessage event is simply not emitted — but the message is still saved to MongoDB. The next time the receiver opens or refreshes the conversation, GET /api/messages/:id will return the full history including any messages they missed.

Build docs developers (and LLMs) love

Get started for freeTalk to us