Documentation
API Documentation/Socket Endpoints

Socket Endpoints

Documentation for xTimer API socket.io endpoints

Socket.io Endpoints

The xTimer API offers a Socket.io endpoint for real-time updates and interactions. This endpoint receives push messages from the server whenever there is a change in a room. These changes can be triggered by the controller page, the API, or the server itself.

Authentication

To authenticate with the Socket.io endpoint, include your room ID and API key in the auth object:

const socket = io("'wss://xtimer.app/socket.io", {
  auth: {
    roomId: "YOUR_ROOM_ID",
    apiKey: "YOUR_API_KEY"
  }
});

Connection Events

connect

Emitted when the socket successfully connects to the server.

socket.on("connect", () => {
  console.log("Connected to xTimer Socket.io server");
});

disconnect

Emitted when the socket disconnects from the server.

socket.on("disconnect", (reason) => {
  console.log("Disconnected from xTimer Socket.io server:", reason);
});

connect_error

Emitted when a connection error occurs.

socket.on("connect_error", (error) => {
  console.error("Connection error:", error.message);
});

Room Events

room-name-updated

Emitted when the room name is updated.

socket.on("room-name-updated", (data) => {
  console.log("Room name updated:", data.name);
  // data: { id: "room-id", pid: "room-pid", name: "New Room Name" }
});

room-timezone-updated

Emitted when the room timezone is updated.

socket.on("room-timezone-updated", (data) => {
  console.log("Room timezone updated:", data.timezone);
  // data: { id: "room-id", pid: "room-pid", timezone: "Europe/Berlin" }
});

settings-update

Emitted when room settings are updated.

socket.on("settings-update", (settings) => {
  console.log("Room settings updated:", settings);
  // settings: { logo: {...}, fonts: {...}, timer: {...}, ... }
});

blackout

Emitted when blackout mode is toggled.

socket.on("blackout", (data) => {
  console.log("Blackout mode:", data.enabled ? "enabled" : "disabled");
  // data: { roomId: "room-pid", enabled: true|false, timestamp: 1665123456789 }
});

focus-message

Emitted when focus message mode is toggled.

socket.on("focus-message", (data) => {
  console.log("Focus message mode:", data.enabled ? "enabled" : "disabled");
  // data: { enabled: true|false, view: "VIEWER", clientName: "Client Name" }
});

Timer Events

timer-started

Emitted when a timer is started.

socket.on("timer-started", (data) => {
  console.log("Timer started:", data);
  // data: { timerId: "timer-id", running: true, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789 }
});

timer-stopped

Emitted when a timer is stopped.

socket.on("timer-stopped", (data) => {
  console.log("Timer stopped:", data);
  // data: { timerId: "timer-id", running: false, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789, elapsedTime: 30000, remainingTime: 570000 }
});

timer-reset

Emitted when a timer is reset.

socket.on("timer-reset", (data) => {
  console.log("Timer reset:", data);
  // data: { timerId: "timer-id", running: false, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789 }
});

timer-tweaked

Emitted when a timer's time is adjusted.

socket.on("timer-tweaked", (data) => {
  console.log("Timer tweaked:", data);
  // data: { timerId: "timer-id", running: true|false, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789 }
});

timer-created

Emitted when a new timer is created.

socket.on("timer-created", (timer) => {
  console.log("Timer created:", timer);
  // timer: { id: "timer-id", name: "Timer Name", speaker: "Speaker Name", ... }
});

timer-update

Emitted when a timer is updated.

socket.on("timer-update", (timer) => {
  console.log("Timer updated:", timer);
  // timer: { id: "timer-id", name: "Timer Name", appearance: "COUNTDOWN", ... }
});

timer-deleted

Emitted when a timer is deleted.

socket.on("timer-deleted", (data) => {
  console.log("Timer deleted:", data.id);
  // data: { id: "timer-id" }
});

timer-reorder

Emitted when timers are reordered.

socket.on("timer-reorder", (data) => {
  console.log("Timers reordered:", data.timers);
  // data: { timers: [{ id: "timer-id", index: 1 }, { id: "timer-id", index: 2 }] }
});

timer-flash

Emitted when a flash is triggered.

socket.on("timer-flash", (data) => {
  console.log("Flash triggered:", data.count, "times");
  // data: { count: 3 }
});

timer-changed

Emitted when the active timer is changed.

socket.on("timer-changed", (data) => {
  console.log("Active timer changed:", data);
  // data: { timerId: "timer-id", running: false, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789 }
});

timer-sync

Emitted when timer playback is synchronized.

socket.on("timer-sync", (data) => {
  console.log("Timer synchronized:", data);
  // data: { timerId: "timer-id", running: true|false, deadline: 1665123456789, kickoff: 1665123456789, lastStop: 1665123456789 }
});

Message Events

message-toggle

Emitted when a message's visibility is toggled.

socket.on("message-toggle", (data) => {
  console.log("Message toggled:", data);
  // data: { messageId: "message-id", isVisible: true|false, text: "Message text", color: "white", bold: true, uppercase: false }
});

message-created

Emitted when a new message is created.

socket.on("message-created", (message) => {
  console.log("Message created:", message);
  // message: { messageId: "message-id", text: "Message text", color: "white", showing: false, bold: true, uppercase: false, index: 1 }
});

message-updated

Emitted when a message is updated.

socket.on("message-updated", (message) => {
  console.log("Message updated:", message);
  // message: { messageId: "message-id", text: "Message text", color: "white", showing: false, bold: true, uppercase: false, index: 1 }
});

message-deleted

Emitted when a message is deleted.

socket.on("message-deleted", (data) => {
  console.log("Message deleted:", data.messageId);
  // data: { messageId: "message-id" }
});

message-reorder

Emitted when messages are reordered.

socket.on("message-reorder", (data) => {
  console.log("Messages reordered:", data.messages);
  // data: { messages: [{ id: "message-id", index: 1 }, { id: "message-id", index: 2 }] }
});

message-flash

Emitted when a message flash is triggered.

socket.on("message-flash", (data) => {
  console.log("Message flash triggered:", data);
  // data: { messageId: "message-id", flashes: 3, view: "VIEWER", clientName: "Client Name" }
});

Client Events

client-rename

Emitted when a client is renamed.

socket.on("client-rename", (data) => {
  console.log("Client renamed:", data);
  // data: { clientId: "client-id", name: "New Client Name" }
});

force-reload

Emitted when a client is forced to reload.

socket.on("force-reload", (data) => {
  console.log("Force reload:", data);
  // data: { roomId: "room-pid", clientId: "client-id", userId: "user-id", timestamp: 1665123456789, message: "You have been forced to reload" }
});

kicked

Emitted when a client is kicked from the room.

socket.on("kicked", (data) => {
  console.log("Kicked from room:", data);
  // data: { roomId: "room-pid", clientId: "client-id", userId: "user-id", timestamp: 1665123456789, message: "You have been kicked from the room" }
});

Sending Events from Client to Server

The Socket.io API is primarily for receiving updates from the server. For sending commands to the server, use the HTTP API. However, socket connections do support some limited client-to-server communication for specific scenarios.

Client Identification

When connecting, clients can identify themselves with optional metadata:

const socket = io("wss://xtimer.app/socket.io", {
  auth: {
    roomId: "YOUR_ROOM_ID",
    apiKey: "YOUR_API_KEY",
    clientName: "My Custom Device",
    viewType: "VIEWER" // CONTROLLER, VIEWER, AGENDA, or MODERATOR
  }
});

This helps identify the client in the connected devices list.

HTTP Endpoints

Documentation for xTimer API HTTP endpoints

On this page