API Documentation

Real-time messaging API with WebSocket and HTTP endpoints. Supports room-based messaging and project-wide broadcasts.

Base URL

HTTP: https://api.socket-base.com

WebSocket: wss://api.socket-base.com

Authentication

Project Hash and JWT

Hash: Your project hash identifier. Each project has a unique hash that routes requests to the correct project.
JWT: JSON Web Token used to authenticate users. The JWT must be signed with your project's jwt_secret and contains user information (the sub field identifies the user).

WebSocket

URL Pattern

wss://api.socket-base.com/ws/:hash?jwt=TOKEN

Example:

wss://api.socket-base.com/ws/abc123?jwt=eyJhbGc...

Replace :hash with your project hash
Replace TOKEN with a valid JWT signed with your project's jwt_secret
JWT sub field identifies the authenticated user

HTTP Endpoints

Base URL

https://api.socket-base.com/api

Required Headers

x-hash: Your project hash identifier
Authorization: Bearer JWT_TOKEN (JWT token for user authentication)

All endpoints under /api/* require these headers.

WebSocket API

Connection

const ws = new WebSocket('wss://api.socket-base.com/ws/YOUR_PROJECT_HASH?jwt=YOUR_JWT_TOKEN');

Message Format

All messages are JSON:

{
  "type": "join|leave|message|broadcast",
  "room": "room-name",  // required for join, leave, message
  "payload": "string"   // required for message, broadcast
}

Message Types

1. Join Room

Join a room to receive messages from that room.

{
  "type": "join",
  "room": "chat-room-1"
}

Response: {"type": "joined", "room": "chat-room-1"}

2. Leave Room

Leave a room to stop receiving messages.

{
  "type": "leave",
  "room": "chat-room-1"
}

Response: {"type": "left", "room": "chat-room-1"}

3. Send Message

Send a message to a room. Must be a member of the room.

{
  "type": "message",
  "room": "chat-room-1",
  "payload": "Hello, world!"
}

Message is stored in database
Broadcasted to all members of the room
Returns error if not a member

4. Broadcast

Send a message to all clients in the project (regardless of room membership).

{
  "type": "broadcast",
  "payload": "System announcement"
}

No room field required
Sent to all connected clients for the project

Error Responses

{
  "type": "error",
  "message": "Error description"
}

HTTP API

POST /message

Send a message to a room via HTTP.

https://api.socket-base.com/api/message

Headers

x-hash: Your project hash
Authorization: Bearer JWT_TOKEN (JWT for user authentication)

Body

{
  "room": "chat-room-1",
  "payload": "Hello from HTTP"
}

Response

{
  "success": true
}

POST /broadcast

Broadcast a message to all clients via HTTP.

https://api.socket-base.com/api/broadcast

Headers

x-hash: Your project hash
Authorization: Bearer JWT_TOKEN (JWT for user authentication)

Body

{
  "room": "chat-room-1",  // Note: room field is required but broadcast goes to all
  "payload": "System message"
}

Response

{
  "success": true
}

Usage Flows

Flow 1: Room-Based Chat

1. Connect WebSocket: wss://api.socket-base.com/ws/YOUR_PROJECT_HASH?jwt=YOUR_JWT_TOKEN

2. Join room: {"type": "join", "room": "general"}

3. Send message: {"type": "message", "room": "general", "payload": "Hello"}

4. Receive messages from other room members

5. Leave room: {"type": "leave", "room": "general"}

Flow 2: HTTP to WebSocket

1. Client A connects via WebSocket to wss://api.socket-base.com/ws/YOUR_PROJECT_HASH?jwt=JWT_A and joins room "notifications"

2. Client B sends HTTP POST to https://api.socket-base.com/api/message with headers (x-hash: YOUR_PROJECT_HASH, Authorization: Bearer JWT_B) and body {"room": "notifications", "payload": "Hello"}

3. Client A receives the message via WebSocket

Flow 3: Broadcast

1. Multiple clients connect via WebSocket to wss://api.socket-base.com/ws/YOUR_PROJECT_HASH?jwt=JWT_TOKEN

2. Send broadcast via WebSocket: {"type": "broadcast", "payload": "Alert"} OR via HTTP POST to https://api.socket-base.com/api/broadcast with headers (x-hash: YOUR_PROJECT_HASH, Authorization: Bearer JWT_TOKEN)

3. All connected clients for the project receive the message

Important Notes

Project Hash: The hash identifies your project and routes all requests to the correct project instance
JWT Authentication: JWT tokens authenticate users. Each JWT must be signed with your project's jwt_secret. The sub field in the JWT identifies the user
Room Membership: Must join a room before sending/receiving messages to that room
Message Persistence: Messages sent via WebSocket message type are stored in database
Broadcast Scope: Broadcasts reach all clients for the project hash, regardless of room membership
Connection Tracking: Each WebSocket connection has a unique UUID
Multi-Instance: Uses Redis pub/sub for message distribution across server instances

Error Handling

Invalid JSON: {"type": "error", "message": "Invalid JSON"}

Missing room: {"type": "error", "message": "Room required"}

Missing payload: {"type": "error", "message": "Payload required"}

Not in room: {"type": "error", "message": "You must join the room first"}

Unknown type: {"type": "error", "message": "Unknown message type"}