WebSocket API

The WebSocket API enables real-time collaboration on boards.

Connection

• Endpoint: /whiteboard
• Protocol: wss:// (or ws:// for local development)
• Transport: websocket

Authentication

You must provide an authentication token or board UUID (for public boards) during the connection handshake.

Authenticated Connection

const socket = io('https://api.boardapi.io/whiteboard', {
  query: {
    token: 'jwt-token-here'
  }
});

Public Board Connection (Anonymous)

const socket = io('https://api.boardapi.io/whiteboard', {
  query: {
    boardUuid: 'board-uuid-here'
  },
  auth: {
    externalUserName: 'Guest User' // Optional
  }
});

Client Events (Emit)

Join Board

Joins a specific board room.

• Event: board:join
• Payload:

{
  "boardUuid": "board-uuid-string"
}

Create Object

Creates a new object on the board.

• Event: object:create
• Payload:

{
  "objectId": "obj-uuid-string",
  "type": "rectangle",
  "data": { "x": 100, "y": 200, "width": 50, "height": 50, "fill": "#FF0000" },
  "tempId": "temp-uuid-string" // Optional, for optimistic updates
}

Update Object

Updates an existing object.

• Event: object:update
• Payload:

{
  "objectId": "obj-uuid-string",
  "data": { "x": 150, "y": 250 }
}

Delete Object

Deletes an object from the board.

• Event: object:delete
• Payload:

{
  "objectId": "obj-uuid-string"
}

Cursor Move

Updates the user's cursor position.

• Event: cursor:move
• Payload:

{
  "x": "100.5",
  "y": "200.3",
  "color": "#FF0000" // Optional
}

History Operations

Perform undo/redo operations.

• Undo: history:undo (No payload)
• Redo: history:redo (No payload)
• Get State: history:get-state (No payload)

Server Events (Listen)

Object Created

Broadcasted when an object is created by another user.

• Event: object:created
• Payload:

{
  "objectId": "obj-uuid-string",
  "type": "rectangle",
  "data": { ... },
  "version": 1,
  "socketId": "sender-socket-id",
  "timestamp": "2025-11-17T10:00:00.000Z"
}

Object Updated

Broadcasted when an object is updated.

• Event: object:updated
• Payload:

{
  "objectId": "obj-uuid-string",
  "data": { ... },
  "version": 2,
  "socketId": "sender-socket-id",
  "timestamp": "2025-11-17T10:00:00.000Z"
}

Object Deleted

Broadcasted when an object is deleted.

• Event: object:deleted
• Payload:

{
  "objectId": "obj-uuid-string",
  "version": 3,
  "socketId": "sender-socket-id",
  "timestamp": "2025-11-17T10:00:00.000Z"
}

History Events

Broadcasted when undo/redo operations occur.

• Event: history:undone
• Event: history:redone

Presenter Mode Events

Follow Me Mode

Start Follow Me

Teacher starts Follow Me mode, forcing all participants to follow their viewport.

• Event: followme:start
• Payload:

{
  "boardId": "board-uuid-string",
  "allowBreakaway": true,
  "smoothAnimation": true
}

Stop Follow Me

Teacher stops Follow Me mode.

• Event: followme:stop
• Payload:

{
  "boardId": "board-uuid-string"
}

Follow Me Viewport Update

Teacher sends viewport updates (throttled to 20 updates/sec).

• Event: followme:viewport
• Payload:

{
  "boardId": "board-uuid-string",
  "scrollX": 100.5,
  "scrollY": 200.3,
  "zoom": 1.5
}

Student Breaks Away

Student breaks away from Follow Me mode.

• Event: followme:breakaway
• Payload:

{
  "boardId": "board-uuid-string"
}

Student Rejoins

Student rejoins Follow Me mode.

• Event: followme:rejoin
• Payload:

{
  "boardId": "board-uuid-string"
}

Follow Me Server Events (Listen)

Follow Me Mode Changed

Broadcasted when Follow Me mode is enabled/disabled.

• Event: followme:mode
• Payload:

{
  "type": "followme:mode",
  "enabled": true,
  "leaderId": "user-id",
  "leaderName": "Teacher Name",
  "config": {
    "enabled": true,
    "allowBreakaway": true,
    "showFollowerCount": true,
    "syncInterval": 50,
    "smoothAnimation": true
  },
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Follow Me Viewport Update

Broadcasted viewport updates from teacher to followers.

• Event: followme:viewport
• Payload:

{
  "type": "followme:viewport",
  "scrollX": 100.5,
  "scrollY": 200.3,
  "zoom": 1.5,
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Follow Me Status Update

Broadcasted follower status changes.

• Event: followme:status
• Payload:

{
  "type": "followme:status",
  "following": ["user-id-1", "user-id-2"],
  "breakaway": ["user-id-3"],
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Spectate Mode

Start Spectating

Teacher starts spectating a student.

• Event: spectate:start
• Payload:

{
  "boardId": "board-uuid-string",
  "targetParticipantId": "student-user-id",
  "stealthMode": false
}

Stop Spectating

Teacher stops spectating.

• Event: spectate:stop
• Payload:

{
  "boardId": "board-uuid-string"
}

Spectate Viewport Update

Student sends viewport updates for spectating teacher (throttled to 10 updates/sec).

• Event: spectate:viewport
• Payload:

{
  "boardId": "board-uuid-string",
  "scrollX": 100.5,
  "scrollY": 200.3,
  "zoom": 1.5,
  "cursorX": 150.0,
  "cursorY": 250.0
}

Spectate Server Events (Listen)

Spectate Started

Sent to student when teacher starts spectating (unless stealth mode).

• Event: spectate:start
• Payload:

{
  "type": "spectate:start",
  "observerId": "teacher-user-id",
  "observerName": "Teacher Name",
  "targetId": "student-user-id",
  "stealthMode": false,
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Spectate Viewport

Sent to teacher with student's viewport updates.

• Event: spectate:viewport
• Payload:

{
  "type": "spectate:viewport",
  "targetId": "student-user-id",
  "scrollX": 100.5,
  "scrollY": 200.3,
  "zoom": 1.5,
  "cursorX": 150.0,
  "cursorY": 250.0,
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Spectate Ended

Sent to student when teacher stops spectating.

• Event: spectate:end
• Payload:

{
  "type": "spectate:end",
  "observerId": "teacher-user-id",
  "targetId": "student-user-id",
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Frame Events

Navigate to Frame

Teacher directs all participants to a specific frame.

• Event: frame:navigate
• Payload:

{
  "boardId": "board-uuid-string",
  "frameId": "frame-uuid-string",
  "animate": true
}

Frame Lock Mode

Teacher changes the lock mode of a frame.

• Event: frame:lock
• Payload:

{
  "boardId": "board-uuid-string",
  "frameId": "frame-uuid-string",
  "lockMode": "soft"
}

Frame Server Events (Listen)

Frame Navigated

Broadcasted when teacher navigates to a frame.

• Event: frame:navigated
• Payload:

{
  "frameId": "frame-uuid-string",
  "bounds": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "animate": true,
  "initiatorId": "teacher-user-id",
  "priority": "host",
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Frame Locked

Broadcasted when frame lock mode changes.

• Event: frame:locked
• Payload:

{
  "frameId": "frame-uuid-string",
  "lockMode": "soft",
  "timestamp": "2025-11-26T10:00:00.000Z"
}

Lock Modes

Mode	Description
none	No restrictions, participants can navigate freely
soft	Warning shown when leaving frame, but allowed
hard	Participants cannot leave frame bounds