Messages

Messages are stored in Redis with the room’s TTL and broadcast in realtime to all connected users.

Send message

Requires authentication via roomId query parameter and x-auth-token cookie.

Sends a message to a chat room. The message is stored in the room’s history and broadcast to all connected users via the realtime channel.

curl -X POST "https://your-domain.com/api/messages?roomId=V1StGXR8_Z5jdHi6B-myT" \
  -H "Cookie: x-auth-token=your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "Alice",
    "text": "Hello, everyone!"
  }'

Query parameters

roomId

string

required

The unique identifier of the room where the message will be sent

Body parameters

sender

string

required

The name of the message sender. Maximum length: 100 characters.

text

string

required

The message content. Maximum length: 1000 characters.

Response

Returns an empty response with status 200 on success.

Validation rules

sender must be a string with maximum 100 characters
text must be a string with maximum 1000 characters
The room must exist (returns error if room does not exist)

Error responses

Show Room does not exist

{
  "error": "Room does not exist"
}

Show Validation error

{
  "error": "Validation error"
}

Message structure

When a message is successfully sent, it’s stored with the following structure:

string

Unique message identifier (generated using nanoid)

sender

string

The sender name from the request

text

string

The message content from the request

timestamp

number

Unix timestamp in milliseconds when the message was created

roomId

string

The room identifier

token

string

The sender’s auth token (only visible to the sender)

Get messages

Requires authentication via roomId query parameter and x-auth-token cookie.

Retrieves all messages from a chat room’s history.

curl -X GET "https://your-domain.com/api/messages?roomId=V1StGXR8_Z5jdHi6B-myT" \
  -H "Cookie: x-auth-token=your-token-here"

Query parameters

roomId

string

required

The unique identifier of the room to retrieve messages from

Response

messages

array

required

An array of message objects in chronological order

Show Message object properties

string

Unique message identifier

sender

string

The name of the message sender

text

string

The message content

timestamp

number

Unix timestamp in milliseconds

roomId

string

The room identifier

token

string

The auth token. Only present for messages sent by the requesting user (when the message token matches the request token).

Show Example response

{
  "messages": [
    {
      "id": "V1StGXR8_Z5jdHi6B-myT",
      "sender": "Alice",
      "text": "Hello, everyone!",
      "timestamp": 1709481600000,
      "roomId": "room-123",
      "token": "user-token-abc"
    },
    {
      "id": "a2bGz9Kp_Q8fgLx3M-pqR",
      "sender": "Bob",
      "text": "Hi Alice!",
      "timestamp": 1709481605000,
      "roomId": "room-123"
    }
  ]
}

Privacy note

The token field is only included in messages that were sent by the requesting user. This allows the client to identify which messages belong to the current user without exposing other users’ tokens.

Architecture

API

Send message

Query parameters

Body parameters

Response

Validation rules

Error responses

Message structure

Get messages

Query parameters

Response

Privacy note

Build docs developers (and LLMs) love

Architecture

API

​Send message

​Query parameters

​Body parameters

​Response

​Validation rules

​Error responses

​Message structure

​Get messages

​Query parameters

​Response

​Privacy note

Build docs developers (and LLMs) love

Send message

Query parameters

Body parameters

Response

Validation rules

Error responses

Message structure

Get messages

Query parameters

Response

Privacy note