Polls API
Confused about "Polls API"?
Let us know how we can improve our documentation:
- On This Page:
- Key Features Include:
- Creating a poll and sending it as part of a message
- Poll options
- Example poll response as part of a message:
- Casting a vote
- Send vote on option
- Send an answer (if answers are configured to be allowed)
- Removing a vote
- Closing a poll
- Retrieving a poll
- Updating a poll
- Full update:
- Partial update:
- Deleting a poll
- Adding, updating and deleting poll options
- Add poll option
- Update poll option
- Delete poll option
- Querying votes
- Votes Queryable Built-In Fields
- Querying polls
- Poll Queryable Built-In Fields
- Poll updated event
- Poll closed event
- Poll deleted event
- Vote casted event
- Vote removed event
- Vote changed event
- App permissions
- Channel permissions:
The Polls feature provides a comprehensive API that enables seamless integration of polling capabilities within your application, enhancing engagement and interaction among users. Through this API, developers can effortlessly create, manage, and utilize polls as part of messages, gather user opinions, and make informed decisions based on real-time feedback.
Key Features Include:
Copied!Confused about "Key Features Include:"?
Let us know how we can improve our documentation:
Easy Poll Creation and Configuration: Developers can create polls with customizable options, descriptions, and configurations, including setting voting visibility (public or anonymous), enforcing unique votes, and specifying the maximum votes a user can cast. Polls can also be designed to allow user-suggested options or open-ended answers, providing flexibility in how you engage with your audience.
Seamless Integration with Messages: Once created, polls can be sent as part of messages, allowing for a seamless user experience. Users can view poll details and participate directly within the context of a conversation.
Dynamic Poll Management: Polls are not static. You can update poll details, add or modify options, and even close polls to further responses. These actions can be performed through full or partial updates, giving you control over the poll's lifecycle.
Robust Voting System: Users can cast votes on options or provide answers to open-ended questions, with the API supporting both single and multiple choice responses. Votes can be changed or removed, ensuring users' opinions are accurately captured.
Comprehensive Query Capabilities: Retrieve detailed information about polls and votes based on various criteria, including poll status, creation time, and user responses. This enables developers to implement rich, data-driven features in their applications.
Customizability and Extensibility: In addition to predefined poll properties, the API supports custom properties, allowing developers to tailor polls and options to their specific needs while maintaining performance and scalability.
APIs
Copied!Confused about "APIs"?
Let us know how we can improve our documentation:
Creating a poll and sending it as part of a message
Copied!Confused about "Creating a poll and sending it as part of a message"?
Let us know how we can improve our documentation:
Creating a poll is easy. You simply create a poll with your desired configuration, and once created, you send a message with the poll id.
When creating a poll, the following properties can be configured:
name | type | description | default | optional |
---|---|---|---|---|
name | string | The name of the poll | - | |
description | string | The description of the poll | - | ✓ |
voting_visibility | enum | Designates whether the votes are casted anonymously | public | ✓ |
enforce_unique_vote | boolean | Designates whether the poll is multiple choice or single choice | false | ✓ |
max_votes_allowed | number | Designates how many votes a single user is allowed to cast on a poll. Allowed value is in range from 1 to 10. If null, no limits applied. | null | ✓ |
allow_user_suggested_options | boolean | Designates weather user can add custom options to the poll | false | ✓ |
allow_answers | boolean | Designates whether user can add an answer to the poll. Max 1 answer is allowed. This is for open ended polls. | false | |
is_closed | boolean | Whether the poll is closed for voting or not | false | ✓ |
options | array of poll option objects | One or more options users can vote on. See below for more information on poll options | - | ✓ |
Poll options
Copied!Confused about "Poll options"?
Let us know how we can improve our documentation:
name | type | description | default | optional |
---|---|---|---|---|
text | string | The text of the poll option | - | ✓ |
Besides the above mentioned properties, it is also possible to supply your own custom properties for both polls and options:
Example poll response as part of a message:
Copied!Confused about "Example poll response as part of a message:"?
Let us know how we can improve our documentation:
latest_votes_by_option
will contain at most the 10 latest votes for that particular option.Casting a vote
Copied!Confused about "Casting a vote"?
Let us know how we can improve our documentation:
Once a poll has been send as part of a message (and as long as the poll isn’t closed for voting). Votes can be casted
Send vote on option
Copied!Confused about "Send vote on option"?
Let us know how we can improve our documentation:
Send an answer (if answers are configured to be allowed)
Copied!Confused about "Send an answer (if answers are configured to be allowed)"?
Let us know how we can improve our documentation:
Few points to note here:
Copied!If
enforce_unique_votes
is set to true on poll, then any vote casted on option will replace the previous vote. Also this api will broadcast an event:poll.vote_changed
ifenforce_unique_votes
is trueOtherwise
poll.vote_casted
event will be broadcasted
Adding an answer will always replace the previous answer. This ensures that user can add maximum
1
answer (similar to what Polly app has)You need
CastVote
permission to be able to cast a voteAPI will return an error if poll is not attached to a message.
Removing a vote
Copied!Confused about "Removing a vote"?
Let us know how we can improve our documentation:
A vote can be removed as well:
Closing a poll
Copied!Confused about "Closing a poll"?
Let us know how we can improve our documentation:
If you want to prevent any further votes on a poll, you can close a poll for voting:
Retrieving a poll
Copied!Confused about "Retrieving a poll"?
Let us know how we can improve our documentation:
If you know the id of a poll you can easily retrieve the poll by using the getPoll
method. If you don’t know the id or if you want to retrieve multiple polls, use the query polls method (see below)
Updating a poll
Copied!Confused about "Updating a poll"?
Let us know how we can improve our documentation:
There are two ways to update a poll: a full poll update and a partial update.
Full update:
Copied!Confused about "Full update:"?
Let us know how we can improve our documentation:
Partial update:
Copied!Confused about "Partial update:"?
Let us know how we can improve our documentation:
Deleting a poll
Copied!Confused about "Deleting a poll"?
Let us know how we can improve our documentation:
Deleting a poll removes the poll, its associated options as well as all the votes on that poll. Be aware that removing a poll can’t be undone.
Adding, updating and deleting poll options
Copied!Confused about "Adding, updating and deleting poll options"?
Let us know how we can improve our documentation:
Poll options can be added, updated or deleted after a poll has been created:
Add poll option
Copied!Confused about "[object Object]"?
Let us know how we can improve our documentation:
allow_user_suggested_options
is set to true
on poll, then user only needs CastVote
permission to access this endpoint. Otherwise user needs UpdatePoll
permission.Update poll option
Copied!Confused about "Update poll option"?
Let us know how we can improve our documentation:
Delete poll option
Copied!Confused about "Delete poll option"?
Let us know how we can improve our documentation:
Querying votes
Copied!Confused about "Querying votes"?
Let us know how we can improve our documentation:
You are able to query the votes on a poll:
Votes Queryable Built-In Fields
Copied!Confused about "Votes Queryable Built-In Fields"?
Let us know how we can improve our documentation:
Name | Type | Description | Supported operators | Example |
---|---|---|---|---|
id | string or list of strings | the ID of the vote | $in, $eq | { id: { $in: [ 'abcd', 'defg' ] } } |
user_id | string or list of strings | the ID of the user who casted the vote | $in, $eq | { $user_id: { $eq: 'abcd' } } |
created_at | string, must be formatted as an RFC3339 timestamp | the time the vote was created | $eq, $gt, $lt, $gte, $lte | { created_at: { $gte: '2023-12-04T09:30:20.45Z' } } |
is_answer | boolean | whether or not the vote is suggested by the user | $eq | { is_answer: { $eq: true } } |
option_id | string or list of strings | The ID of the option the vote was casted on | $in, $eq, $exists | { option_id: { $in: [ 'abcd', 'defg' ] } } |
Querying polls
Copied!Confused about "Querying polls"?
Let us know how we can improve our documentation:
It is also possible to query for polls based on certain filter criteria:
Poll Queryable Built-In Fields
Copied!Confused about "Poll Queryable Built-In Fields"?
Let us know how we can improve our documentation:
Name | type | Description | Supported operations | Example |
---|---|---|---|---|
id | string or list of strings | the ID of the vote | $in, $eq | { id: { $in: [ 'abcd', 'defg' ] } } |
poll_id | string or list of strings | the ID of the poll | $in, $eq | { poll_id: { $in: [ 'abcd', 'defg' ] } } |
name | string or list of strings | the ID of the user who casted the vote | $in, $eq | { name: { $eq: 'abcd' } } |
voting_visibility | string | indicates whether the votes are casted anonymously | $eq | { voting_visibility: { $eq: 'anonymous' } } |
max_votes_allowed | number | the maximum amount of votes per user | $eq, $ne, $gt, $lt, $gte, $lte | { max_votes_allowed: { $gte: 5 } } |
allow_user_suggested_options | boolean | indicates whether the poll allows user suggested options | $eq | { allow_user_suggested_options: { $eq: false } } |
allow_answers | boolean | indicates whether the poll allows user answers | $eq | { allow_answers: { $eq: false } } |
is_closed | boolean | indicates whether the poll is closed for voting | $eq | { is_closed: { $eq: true } } |
created_at | string, must be formatted as an RFC3339 timestamp | the time the poll was created | $eq, $gt, $lt, $gte, $lte | { created_at: {$gte: ‘2023-12-04T09:30:20.45Z’ } |
updated_at | string, must be formatted as an RFC3339 timestamp | the time the poll was updated | $eq, $gt, $lt, $gte, $lte | { updated_at: {$gte: ‘2023-12-04T09:30:20.45Z’ } |
created_by_id | string or list of strings | the ID of the user who created the poll | $in, $eq | { id: { $in: [ 'abcd', 'defg' ] } } |
Events
Copied!Confused about "Events"?
Let us know how we can improve our documentation:
The following websocket events will be emitted:
poll.updated
whenever a poll (or its options) gets updated.poll.closed
whenever a poll is closed for voting.poll.deleted
whenever a poll gets deleted.poll.vote_casted
whenever a vote is casted.poll.vote_removed
whenever a vote is removed.poll.vote_changed
whenever a vote is changed (case of enforce_unique_vote as true)
Poll updated event
Copied!Confused about "Poll updated event"?
Let us know how we can improve our documentation:
Poll closed event
Copied!Confused about "Poll closed event"?
Let us know how we can improve our documentation:
Poll deleted event
Copied!Confused about "Poll deleted event"?
Let us know how we can improve our documentation: