TalkBox Messages API: Send and Retrieve Chat Messages

The messages endpoints expose the persistent layer of TalkBox’s chat system. They let you create message records, retrieve every message you have sent or received, and load the full history of a one-to-one conversation. All three routes are protected — every request must include a valid Bearer token. For real-time delivery the TalkBox server also broadcasts messages over Socket.IO; the HTTP endpoint is best used for persisting messages or loading history on initial page load. All endpoints below require the following header:

Authorization: Bearer <token>

POST /api/messages

Creates a new Message document in MongoDB. The authenticated user is automatically set as the sender; only receiver and content must be provided in the request body. The content string is trimmed before storage.

While this endpoint persists messages to the database, TalkBox uses Socket.IO as the primary real-time delivery channel. In a typical flow the client emits a socket event that both saves the message and pushes it to the recipient instantly. Use this HTTP endpoint when you need direct REST-based message creation.

Request body

receiver

string

required

The MongoDB ObjectId (24-character hex string) of the user who will receive the message.

content

string

required

The text content of the message. Whitespace is trimmed from both ends. An empty string after trimming is rejected with 400.

Success response — `201 Created`

The full Message document as stored in MongoDB:

{
  "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
  "sender": "64f1a2b3c4d5e6f7a8b9c0d1",
  "receiver": "64f1a2b3c4d5e6f7a8b9c0d2",
  "content": "Hey Bob, how are you?",
  "createdAt": "2024-01-14T10:30:00.000Z",
  "updatedAt": "2024-01-14T10:30:00.000Z"
}

_id

string

The unique MongoDB ObjectId of the created message.

sender

string

The ObjectId of the user who sent the message (derived from the JWT — not the request body).

receiver

string

The ObjectId of the intended recipient, as supplied in the request body.

content

string

The trimmed text content of the message.

createdAt

string

ISO 8601 timestamp of when the document was created (added automatically by Mongoose timestamps).

updatedAt

string

ISO 8601 timestamp of the last update (added automatically by Mongoose timestamps).

Error responses

Status	Condition
`400 Bad Request`	`receiver` or `content` is missing, not a string, or `content` is empty after trimming
`401 Unauthorized`	The `Authorization` header is absent, malformed, or the token is invalid
`500 Internal Server Error`	An unexpected server or database error occurred

Show 400 error response examples

{ "message": "Receiver and content are required." }
{ "message": "Invalid receiver." }
{ "message": "Invalid content." }
{ "message": "Content cannot be empty." }

Example

curl -X POST http://localhost:3000/api/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "receiver": "64f1a2b3c4d5e6f7a8b9c0d2",
    "content": "Hey Bob, how are you?"
  }'

{
  "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
  "sender": "64f1a2b3c4d5e6f7a8b9c0d1",
  "receiver": "64f1a2b3c4d5e6f7a8b9c0d2",
  "content": "Hey Bob, how are you?",
  "createdAt": "2024-01-14T10:30:00.000Z",
  "updatedAt": "2024-01-14T10:30:00.000Z"
}

GET /api/messages

Returns every Message document where the authenticated user is either the sender or the receiver. This gives a complete inbox/outbox view. Documents are returned in default MongoDB order (insertion order) and are not populated — sender and receiver fields are raw ObjectIds.

Request body

None.

Success response — `200 OK`

An array of Message documents. Returns an empty array [] if the user has no messages.

[
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
    "sender": "64f1a2b3c4d5e6f7a8b9c0d1",
    "receiver": "64f1a2b3c4d5e6f7a8b9c0d2",
    "content": "Hey Bob, how are you?",
    "createdAt": "2024-01-14T10:30:00.000Z",
    "updatedAt": "2024-01-14T10:30:00.000Z"
  },
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e4",
    "sender": "64f1a2b3c4d5e6f7a8b9c0d2",
    "receiver": "64f1a2b3c4d5e6f7a8b9c0d1",
    "content": "Doing great, thanks!",
    "createdAt": "2024-01-14T10:31:00.000Z",
    "updatedAt": "2024-01-14T10:31:00.000Z"
  }
]

Error responses

Status	Condition
`401 Unauthorized`	The `Authorization` header is absent, malformed, or the token is invalid
`500 Internal Server Error`	An unexpected server or database error occurred

Example

curl -X GET http://localhost:3000/api/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

[
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
    "sender": "64f1a2b3c4d5e6f7a8b9c0d1",
    "receiver": "64f1a2b3c4d5e6f7a8b9c0d2",
    "content": "Hey Bob, how are you?",
    "createdAt": "2024-01-14T10:30:00.000Z",
    "updatedAt": "2024-01-14T10:30:00.000Z"
  }
]

GET /api/messages/:userId

Returns the full chronological conversation history between the authenticated user and another user identified by the :userId path parameter. The query matches all messages where one participant is the caller and the other is :userId, sorted by createdAt ascending (oldest first). The sender and receiver fields are populated with the referenced user’s _id and username.

Path parameters

userId

string

required

The MongoDB ObjectId (24-character hex string) of the other participant in the conversation.

Request body

None.

Success response — `200 OK`

An array of populated Message documents sorted oldest-first. Returns an empty array [] if no messages exist between the two users.

[
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
    "sender": {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "username": "alice"
    },
    "receiver": {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d2",
      "username": "bob"
    },
    "content": "Hey Bob, how are you?",
    "createdAt": "2024-01-14T10:30:00.000Z",
    "updatedAt": "2024-01-14T10:30:00.000Z"
  },
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e4",
    "sender": {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d2",
      "username": "bob"
    },
    "receiver": {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "username": "alice"
    },
    "content": "Doing great, thanks!",
    "createdAt": "2024-01-14T10:31:00.000Z",
    "updatedAt": "2024-01-14T10:31:00.000Z"
  }
]

_id

string

The unique MongoDB ObjectId of the message.

sender

object

The populated sender user object.

Show sender fields

_id

string

The sender’s MongoDB ObjectId.

username

string

The sender’s display name.

receiver

object

The populated receiver user object.

Show receiver fields

_id

string

The receiver’s MongoDB ObjectId.

username

string

The receiver’s display name.

content

string

The trimmed text content of the message.

createdAt

string

ISO 8601 creation timestamp. Messages are sorted by this field in ascending order.

updatedAt

string

ISO 8601 last-updated timestamp.

Error responses

Status	Condition
`400 Bad Request`	The `:userId` path parameter is missing or not a string
`401 Unauthorized`	The `Authorization` header is absent, malformed, or the token is invalid
`500 Internal Server Error`	An unexpected server or database error occurred

Show Error response examples

{ "message": "Missing other user id." }
{ "message": "Invalid other user id." }
{ "message": "Unauthorized." }
{ "message": "Internal server error." }

Example

curl -X GET http://localhost:3000/api/messages/64f1a2b3c4d5e6f7a8b9c0d2 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

[
  {
    "_id": "65a3b4c5d6e7f8a9b0c1d2e3",
    "sender": { "_id": "64f1a2b3c4d5e6f7a8b9c0d1", "username": "alice" },
    "receiver": { "_id": "64f1a2b3c4d5e6f7a8b9c0d2", "username": "bob" },
    "content": "Hey Bob, how are you?",
    "createdAt": "2024-01-14T10:30:00.000Z",
    "updatedAt": "2024-01-14T10:30:00.000Z"
  }
]

Pass the _id of a user returned by GET /api/users directly as the :userId path segment to load your conversation with that person.

REST API

WebSocket

TalkBox Messages API: Send and Retrieve Chat Messages

POST /api/messages

Request body

Success response — `201 Created`

Error responses

Example

GET /api/messages

Request body

Success response — `200 OK`

Error responses

Example

GET /api/messages/:userId

Path parameters

Request body

Success response — `200 OK`

Error responses

Example

Build docs developers (and LLMs) love

REST API

WebSocket

Documentation Index

​POST /api/messages

​Request body

​Success response — 201 Created

​Error responses

​Example

​GET /api/messages

​Request body

​Success response — 200 OK

​Error responses

​Example

​GET /api/messages/:userId

​Path parameters

​Request body

​Success response — 200 OK

​Error responses

​Example

Build docs developers (and LLMs) love

POST /api/messages

Request body

Success response — `201 Created`

Error responses

Example

GET /api/messages

Request body

Success response — `200 OK`

Error responses

Example

GET /api/messages/:userId

Path parameters

Request body

Success response — `200 OK`

Error responses

Example