Poll

Joining the room

JoinSuccess

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

Fields

Field	Type	Always	Description
`id`	`string`	yes	Id of the poll
`topic`	`string`	yes	Topic of the poll
`live`	`bool`	yes	The state of the poll is reported immediately
`multiple_choice`	`bool`	yes	Multiple choices can be selected
`choices`	`Choice[]`	yes	The available choices to vote on, see Choice
`started`	`string`	yes	Timestamp for when the poll was started
`duration`	`int`	yes	Duration of the poll in seconds

Example

{
    "id": "00000000-0000-0000-0000-000000000000",
    "topic": "Yes or No?",
    "live": true,
    "multiple_choice": true,
    "choices": [
        { "id": 0, "content": "first choice" },
        { "id": 1, "content": "second choice" },
        { "id": 2, "content": "third choice" }
    ],
    "started": "2022-10-22T11:22:33Z",
    "duration": 60000
}

Joined

When joining a room, the joined control event sent to all other participants does not contain module-specific data.

Commands

Commands are issued by a participate to start or interact with a poll.

Start

The Start message can be send by a user to start a new poll. New polls can only be created if the current one has finished or has been canceled.

Fields

Field	Type	Required	Description
`action`	`enum`	yes	Must be `"start"`
`topic`	`string`	yes	Topic of the poll
`live`	`bool`	no	The state of the poll is reported immediately, defaults to `false`
`multiple_choice`	`bool`	no	Multiple choices can be selected, defaults to `false`
`choices`	`string[]`	yes	Non empty array of strings which each describe a choice
`duration`	`int`	no	Duration of the poll in seconds

Example

{
    "action": "start",
    "topic": "some topic",
    "live": true,
    "multiple_choice": true,
    "choices": ["first choice", "seconds choice", "third choice"],
    "duration": 60000
}

Response

A Started message is sent to all participants that are currently in the room.

Can return Error of kind insufficient_permissions, invalid_choice_count, invalid_choice_description, invalid_topic_length, invalid_duration, and still_running.

Vote

Cast your vote for a poll with the specified poll_id. Each participant can only vote once per poll.

If a vote is started with the live flag set to true a LiveUpdate is sent to all participants.

For backwards compatibility, both an array of choice ids as well as a single choice id can be specified. The choice_id single value field takes precedence over the choice_ids array field.

Fields

Field	Type	Required	Description
`action`	`enum`	yes	Must be `"vote"`
`poll_id`	`string`	yes	ID of the poll
`choice_id`	`int`	no	ID of a single choice, takes precedence over `choice_ids`
`choice_ids`	`int[]`	no	ID of multiple choices, empty to abstain, only evaluated if `choice_id` is missing

To abstain, both choice_id and choice_ids can be omitted.

Example

{
    "action": "vote",
    "poll_id": "00000000-0000-0000-0000-000000000000",
    "choice_id": 1
}

Response

Can return Error of kind invalid_poll_id, invalid_choice_id and multiple_choice_not_allowed.

Finish

Finish a poll prematurely.

A Done message will be sent to all other participants.

Fields

Field	Type	Required	Description
`action`	`enum`	yes	Must be `"finish"`
`id`	`string`	yes	ID of the poll

Example

{
    "action": "finish",
    "id": "00000000-0000-0000-0000-000000000000"
}

Response

Can return Error of kind insufficient_permissions and invalid_poll_id.

Events

Events are received by participants when the poll state has changed.

Started

A poll has been started.

Fields

Field	Type	Always	Description
`message`	`enum`	yes	Is `"started"`
`id`	`string`	yes	Id of the poll
`topic`	`string`	yes	Topic of the poll
`live`	`bool`	yes	The state of the poll is reported immediately
`multiple_choice`	`bool`	yes	Multiple choices can be selected
`choices`	`Choice[]`	yes	The available choices to vote on, see Choice
`duration`	`int`	yes	Duration of the poll in seconds

Example

{
    "message": "started",
    "id": "00000000-0000-0000-0000-000000000000",
    "topic": "Yes or No?",
    "live": true,
    "multiple_choice": true,
    "choices": [
        { "id": 0, "content": "first choice" },
        { "id": 1, "content": "second choice" },
        { "id": 2, "content": "third choice" }
    ],
    "duration": 60000
}

LiveUpdate

A poll has been updated.

Fields

Field	Type	Always	Description
`message`	`enum`	yes	Is `"live_update"`
`id`	`string`	yes	Id of the poll
`results`	`Choice[]`	yes	List of choices and their scores

Choice Fields:

Field	Type	Always	Description
`id`	`int`	yes	ID of the choice
`count`	`int`	yes	Count of votes for this choice

Example

{
    "message": "live_update",
    "id": "00000000-0000-0000-0000-000000000000",
    "choices": [
        { "id": 0, "count": 3 },
        { "id": 1, "count": 7 },
        { "id": 2, "count": 1 }
    ]
}

Done

A poll has been completed due to expiration or a moderator issuing the Finish command.

Fields

Field	Type	Always	Description
`message`	`enum`	yes	Is `"live_update"`
`id`	`string`	yes	Id of the poll
`results`	`Choice[]`	yes	List of choices and their scores

Choice Fields:

Field	Type	Always	Description
`id`	`int`	yes	ID of the choice
`count`	`int`	yes	Count of votes for this choice

Example

{
    "message": "live_update",
    "id": "00000000-0000-0000-0000-000000000000",
    "choices": [
        { "id": 0, "count": 3 },
        { "id": 1, "count": 7 },
        { "id": 2, "count": 1 }
    ]
}

Error

An error has occurred when issuing a command

Field	Type	Always	Description
`message`	`enum`	yes	Is `"error"`
`error`	`enum`	yes	Variant of the error, see table below

Error	Description
`insufficient_permissions`	The issued command requires greater permissions
`invalid_choice_count`	The Start command specified an invalid amount of choices (must be greater than 2 and fewer than 64)
`invalid_poll_id`	Unknown poll id
`invalid_choice_id`	Unknown choice id
`multiple_choices_not_allowed`	Issued when a Vote command contains more than one choice but multiple choice is disabled for the poll
`invalid_choice_description`	Given choice description was invalid (length must be between 2 and 100 bytes)
`invalid_topic_length`	Given topic length was invalid (must be between 2 and 100 bytes)
`invalid_duration`	Invalid poll duration (must be greater than 2 seconds and shorter than 1 hour)
`still_running`	Tried to start a poll while a poll is still running

Shared Types

Choice

The description of a choice that can be voted on.

Fields

Field	Type	Always	Description
`id`	`int`	yes	ID of the choice
`content`	`string`	yes	Content/Description of the choice