blob: 8d41e105f21041d920b0f0487c67b28e4ced209f (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
# Poll API
Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
## Create a poll in a conversation
* Method: `POST`
* Endpoint: `/poll/{token}`
* Data:
| field | type | Description |
|--------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `question` | string | The question of the poll |
| `options` | string[] | Array of strings with the voting options |
| `resultMode` | int | The result and voting mode of the poll, `0` means participants can immediatelly see the result and who voted for which option. `1` means the result is hidden until the poll is closed and then only the summary is published. |
| `maxVotes` | int | Maximum amount of options a participant can vote for |
* Response:
- Status code:
+ `201 Created`
+ `400 Bad Request` When the room is a one-to-one conversation
+ `400 Bad Request` When the question or the options were too long or invalid (not strings)
+ `403 Forbidden` When the conversation is read-only
+ `403 Forbidden` When the actor does not have chat permissions
+ `404 Not Found` When the conversation could not be found for the participant
+ `412 Precondition Failed` When the lobby is active and the user is not a moderator
- Data:
See [Poll data](#poll-data)
## Get state or result of a poll
* Method: `GET`
* Endpoint: `/poll/{token}/{pollId}`
* Response:
- Status code:
+ `201 Created`
+ `400 Bad Request` In case of any other error
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the poll id could not be found in the conversation
+ `412 Precondition Failed` When the lobby is active and the user is not a moderator
- Data:
See [Poll data](#poll-data)
## Vote on a poll
* Method: `POST`
* Endpoint: `/poll/{token}/{pollId}`
* Data:
| field | type | Description |
|--------------|-------|--------------------------------------------------|
| `optionIds` | int[] | The option IDs the participant wants to vote for |
* Response:
- Status code:
+ `201 Created`
+ `400 Bad Request` When an option id is invalid
+ `400 Bad Request` When too many options were voted
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the poll id could not be found in the conversation
+ `412 Precondition Failed` When the lobby is active and the user is not a moderator
- Data:
See [Poll data](#poll-data)
## Close a poll
* Method: `DELETE`
* Endpoint: `/poll/{token}/{pollId}`
* Response:
- Status code:
+ `200 OK`
+ `400 Bad Request` When the poll is already closed
+ `403 Forbidden` When the participant is not the author of the poll or a moderator
+ `404 Not Found` When the conversation could not be found for the participant
+ `404 Not Found` When the poll id could not be found in the conversation
+ `412 Precondition Failed` When the lobby is active and the user is not a moderator
- Data:
See [Poll data](#poll-data)
## Poll data
!!! note
Due to the structure of the `votes` array the response is not valid in XML.
It is therefor recommended to use `format=json` or send the `Accept: application/json` header,
to receive a JSON response.
| field | type | Description |
|--------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | int | ID of the poll |
| `question` | string | The question of the poll |
| `options` | string[] | The options participants can vote for |
| `votes` | int[] | Map with `'option-' + optionId` => number of votes (only available for when the actor voted on public poll or the poll is closed) |
| `actorType` | string | Actor type of the poll author (see [Constants - Attendee types](constants.md#attendee-types)) |
| `actorId` | string | Actor ID identifying the poll author |
| `actorDisplayName` | string | Display name of the poll author |
| `status` | int | Status of the poll (see [Constants - Poll status](constants.md#poll-status)) |
| `resultMode` | int | Result mode of the poll (see [Constants - Poll mode](constants.md#poll-mode)) |
| `maxVotes` | int | Maximum amount of options a user can vote for, `0` means unlimited |
| `votedSelf` | int[] | Array of option ids the participant voted for |
| `numVoters` | int | The number of unique voters that voted (only available when the actor voted on public poll or the poll is closed unless for the creator and moderators) |
| `details` | array[] | Detailed list who voted for which option (only available for public closed polls), see [Details](#details) below |
### Details
| field | type | Description |
|------------------|--------|--------------------------------------------------------------------------------------------------------------|
| actorType | string | The actor type of the participant that voted (see [Constants - Attendee types](constants.md#attendee-types)) |
| actorId | string | The actor id of the participant that voted |
| actorDisplayName | string | The display name of the participant that voted |
| optionId | int | The option that was voted for |
|
