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.

Socket Endpoints