Zum Hauptinhalt springen

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

FieldTypeAlwaysDescription
timer_idstringyesThe timer id (uuid)
started_atstringyesRFC 3339 timestamp of when the timer started
kindenumyesEither "countdown" or "stopwatch"
ends atstringif kind is "countdown"optional RFC 3339 timestamp of when the timer will end
stylestringnoAn optional style tag to identify a timer across frontend clients
titlestringnoAn optional title for the timer
ready_check_enabledboolyesEnables/Disables participants to send a update_ready_status action
ready_statusboolnoThe 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

FieldTypeAlwaysDescription
ready_statusboolnoThe 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

FieldTypeRequiredDescription
actionenumyesMust be "start"
kindenumyesEither "countdown" or "stopwatch"
durationintif kind is "countdown"The duration (seconds) of the timer
titlestringnoThe optional title for the timer
stylestringnoAn optional style tag to identify a timer across frontend clients
enable_ready_checkboolyesEnables/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

FieldTypeRequiredDescription
actionenumyesMust be "stop"
timer_idstringyesThe timer id (uuid)
reasonstringnoAn 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

FieldTypeRequiredDescription
actionenumyesMust be "update_ready_status"
timer_idstringyesThe timer id (uuid)
statusboolyesThe 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

FieldTypeAlwaysDescription
messageenumyesIs "started"
timer_idstringyesThe timer id (uuid)
kindenumyesEither "countdown" or "stopwatch"
started_atstringyesRFC 3339 timestamp of when the timer started
ends atstringif kind is "countdown"optional RFC 3339 timestamp of when the timer will end
titlestringnoAn optional title for the timer
stylestringnoAn optional style tag to identify a timer across frontend clients
ready_check_enabledboolyesEnables/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

FieldTypeAlwaysDescription
messageenumyesIs "stopped"
timer_idstringyesThe timer id (uuid)
kindenumyesThe kind of stop. Must be "by_moderator", "expired", "creator_left"
participant_idstringwhen kind is by_moderatorThe participant id of the moderator that stopped the timer
reasonstringwhen kind is by_moderatorOptional reason. Set by the moderator

StopKind:

KindDescription
by_moderatorThe timer was stopped manually by a moderator
expiredThe duration of the timer has expired
creator_leftThe 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

FieldTypeAlwaysDescription
messageenumyesIs "updated_ready_status"
timer_idstringyesThe timer id (uuid)
participant_idstringyesThe participant that had its status updated
statusboolyesThe 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

ErrorDescription
insufficient_permissionsThe issued command requires greater permissions
invalid_durationThe provided duration (in a start request) is invalid
timer_already_runningA 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"
}