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 standings of the poll will be reported live |
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,
"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 | yes | Enable/Disable live updates on the poll |
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,
"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
, 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.
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 the choice, none to abstain |
Example
{
"action": "vote",
"poll_id": "00000000-0000-0000-0000-000000000000",
"choice_id": 1,
}
Response
Can return Error of kind invalid_poll_id
and invalid_choice_id
.
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 standings of the poll will be reported live |
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,
"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 |
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 |