Timer

Joining the room

JoinSuccess

When joining a room with a timer running, the join_success control event contains the module-specific fields described below.

Fields

Field	Type	Always	Description
timer_id	string	yes	The timer id (uuid)
started_at	string	yes	RFC 3339 timestamp of when the timer started
kind	enum	yes	Either "countdown" or "stopwatch"
ends at	string	if kind is "countdown"	optional RFC 3339 timestamp of when the timer will end
style	string	no	An optional style tag to identify a timer across frontend clients
title	string	no	An optional title for the timer
ready_check_enabled	bool	yes	Enables/Disables participants to send a update_ready_status action
ready_status	bool	no	The ready status of the participant for a currently active timer

Example

Countdown:

{
    "message": "started",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "countdown",
    "started_at": "1970-01-01T00:00:00Z",
    "ends_at": "1970-01-01T00:00:00Z",
    "title": "Testing the timer!",
    "ready_check_enabled": false,
    "ready_status": false
}

Joined

When joining a room with a timer running, the joined control event sent to all other participants contains the module-specific fields described below.

Fields

Field	Type	Always	Description
ready_status	bool	no	The ready status of the participant for a currently active timer

Example

    ...
    "ready_status": true,
    ...

---

Overview

The timer module allows a moderator to start a timer for all participants in the room.

There are two variations of the timer: "countdown" and "stopwatch".

When the "countdown" kind is configured, the timer continues to run until its duration expires or if a moderator stops it beforehand.

When the "stopwatch" kind is configured, the timer continues to run until a moderator stops it.

There can only be one timer present at a time. Due to a current limitation of our module system, all participants will receive a stopped event when the creator of a timer leaves the room. This behavior shall be fixed in the future.

Commands

Start

The Start action can be sent by a moderator to start a new timer.

Can return Error of kind insufficient_permissions, invalid_duration or timer_already_running

Fields

Field	Type	Required	Description
action	enum	yes	Must be "start"
kind	enum	yes	Either "countdown" or "stopwatch"
duration	int	if kind is "countdown"	The duration (seconds) of the timer
title	string	no	The optional title for the timer
style	string	no	An optional style tag to identify a timer across frontend clients
enable_ready_check	bool	yes	Enables/Disables participants to send a update_ready_check action

When the kind is set to "countdown", the module will automatically send a Stopped message when the duration expires.

Examples

Countdown:

{
    "action": "start",
    "kind": "countdown",
    "duration": 20,
    "title": "Testing the timer!",
    "enable_ready_check": false
}

Countdown with style:

{
    "action": "start",
    "kind": "countdown",
    "duration": 180,
    "style": "coffee_break",
    "enable_ready_check": true
}

Stopwatch:

{
    "action": "start",
    "kind": "stopwatch",
    "title": "Testing the stopwatch!",
    "enable_ready_check": false
}

Response

Each participant receives a Started message with the configuration of the timer.

---

Stop

The Stop action can be sent by a moderator to stop a timer.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "stop"
timer_id	string	yes	The timer id (uuid)
reason	string	no	An optional reason for the stop, set by the moderator

Examples

        {
            "action": "stop",
            "timer_id": "00000000-0000-0000-0000-000000000000",
            "reason": "test"
        }

Response

Each participant receives a Stopped message.

---

Update Ready Status

Set the ready status of a participant.

Can be sent by any participant only when ready_check is set to true in Start.

Fields

Field	Type	Required	Description
action	enum	yes	Must be "update_ready_status"
timer_id	string	yes	The timer id (uuid)
status	bool	yes	The R2C status of the participant

Examples

{
    "action": "update_ready_status",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "status": true
}

Response

Each participant receives a Control Update event with the participant's R2C status.

---

Events

Started

A timer has been started.

Fields

Field	Type	Always	Description
message	enum	yes	Is "started"
timer_id	string	yes	The timer id (uuid)
kind	enum	yes	Either "countdown" or "stopwatch"
started_at	string	yes	RFC 3339 timestamp of when the timer started
ends at	string	if kind is "countdown"	optional RFC 3339 timestamp of when the timer will end
title	string	no	An optional title for the timer
style	string	no	An optional style tag to identify a timer across frontend clients
ready_check_enabled	bool	yes	Enables/Disables participants to send a update_ready_status action

Example

Countdown:

{
    "message": "started",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "countdown",
    "started_at": "1970-01-01T00:00:00Z",
    "ends_at": "1970-01-01T00:00:00Z",
    "title": "Testing the timer!",
    "ready_check_enabled": false
}

Countdown with style:

{
    "message": "started",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "countdown",
    "started_at": "1970-01-01T00:00:00Z",
    "ends_at": "1970-01-01T00:00:00Z",
    "style": "coffee_break",
    "ready_check_enabled": false
}

Stopwatch:

{
    "message": "started",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "stopwatch",
    "started_at": "1970-01-01T00:00:00Z",
    "ends_at": "1970-01-01T00:00:00Z",
    "title": "Testing the stopwatch!",
    "ready_check_enabled": false
}

---

Stopped

A timer has been stopped.

Fields

Field	Type	Always	Description
message	enum	yes	Is "stopped"
timer_id	string	yes	The timer id (uuid)
kind	enum	yes	The kind of stop. Must be "by_moderator", "expired", "creator_left"
participant_id	string	when kind is by_moderator	The participant id of the moderator that stopped the timer
reason	string	when kind is by_moderator	Optional reason. Set by the moderator

StopKind:

Kind	Description
by_moderator	The timer was stopped manually by a moderator
expired	The duration of the timer has expired
creator_left	The creator of the timer has left the room

Example

by moderator:

{
    "message": "stopped",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "by_moderator",
    "participant_id": "00000000-0000-0000-0000-000000000000",
    "reason": "A good reason!"
}

expired:

{
    "message": "stopped",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "expired",
}

creator left:

{
    "message": "creator_left",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "kind": "expired",
}

---

Updated ready status

A participant has updated its ready status.

Fields

Field	Type	Always	Description
message	enum	yes	Is "updated_ready_status"
timer_id	string	yes	The timer id (uuid)
participant_id	string	yes	The participant that had its status updated
status	bool	yes	The participants status

Examples

{
    "message": "updated_ready_status",
    "timer_id": "00000000-0000-0000-0000-000000000000",
    "participant_id": "00000000-0000-0000-0000-000000000000",
    "status": true,
}

---

Error

An error has occurred while issuing a command.

Fields

Error	Description
insufficient_permissions	The issued command requires greater permissions
invalid_duration	The provided duration (in a start request) is invalid
timer_already_running	A timer is already running while trying to start a new one

Examples

{
    "message":"error",
    "error":"insufficient_permissions"
}

{
    "message":"error",
    "error":"invalid_duration"
}

{
    "message":"error",
    "error":"timer_already_running"
}