Messages API
Endpoints for sending, retrieving, and managing messages in chat rooms.
Overview
Messages are the core communication unit in chat rooms. Authenticated users can send messages, and read access depends on room visibility (public/private membership).
Endpoint Summary
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/rooms/{id}/messages | List messages | No |
| POST | /api/rooms/{id}/messages | Send message | Yes |
| DELETE | /api/rooms/{id}/messages/{messageId} | Delete message | Yes (admin) |
| GET | /api/messages/bulk?roomIds=... | Bulk fetch messages | No |
Endpoints
List Messages
Get message history for a room.
GET /api/rooms/{id}/messages?limit=50| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Max messages to return (default: 20, max: 500) |
{
"messages": [
{
"id": "msg123",
"roomId": "general",
"username": "alice",
"content": "Hello everyone!",
"timestamp": 1704067200000
},
{
"id": "msg124",
"roomId": "general",
"username": "bob",
"content": "Hi Alice!",
"timestamp": 1704067260000
}
]
}Send Message
Send a message to a room. Requires authentication.
POST /api/rooms/{id}/messages
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json
{
"content": "Hello world!"
}| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Message content (max 1000 chars) |
{
"message": {
"id": "msg125",
"roomId": "general",
"username": "alice",
"content": "Hello world!",
"timestamp": 1704067320000
}
}Delete Message (Admin)
Delete a specific message. Admin only.
DELETE /api/rooms/{roomId}/messages/{messageId}
Authorization: Bearer {token}
X-Username: ryo{
"success": true
}Bulk Fetch Messages
Fetch messages from multiple rooms in a single request.
GET /api/messages/bulk?roomIds=general,random,private123| Parameter | Type | Required | Description |
|---|---|---|---|
roomIds | string | Yes | Comma-separated room IDs |
{
"messagesMap": {
"general": [{ "id": "msg123", "username": "alice", "content": "Hello!", "timestamp": 1704067200000 }],
"random": []
},
"validRoomIds": ["general", "random"],
"invalidRoomIds": ["private123"]
}Rate Limits
Messages in public rooms have burst protection:
| Limit Type | Window | Max Messages |
|---|---|---|
| Short burst | 10 seconds | 3 messages |
| Long burst | 1 minute | 20 messages |
| Min interval | - | 2 seconds between messages |
Private rooms have relaxed rate limits.
Message Format
Messages contain the following fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique message identifier |
roomId | string | Room the message belongs to |
username | string | Author's username |
content | string | Message text content |
timestamp | number | Unix timestamp (milliseconds) |
Error Responses
| Status | Error | Description |
|---|---|---|
| 400 | Invalid request | Missing or invalid parameters |
| 400 | Message exceeds maximum length of 1000 | Message too long |
| 401 | Authentication required | Token missing or invalid |
| 403 | Forbidden | Not authorized to delete (non-admin) |
| 404 | Room not found | Room ID doesn't exist |
| 404 | Message not found | Message ID doesn't exist |
| 429 | Rate limit exceeded | Too many messages too quickly |
Related
- Rooms API - Room endpoints
- Presence API - Presence tracking
- Auth API - Authentication endpoints