Skip to main content
Polls are posted as messages in a topic. When you create a poll, each option is stored with a server-generated 6-character ID. You use those IDs when submitting votes.

​
Create a Poll

POST https://api.zenzap.co/v2/polls
The bot must be a member of the topic. A poll message is sent on behalf of the bot. 
{
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    "Bug fixes",
    "New features",
    "Performance improvements"
  ],
  "selectionType": "single"
}
Response — 201 Created: 
{
  "id": "770e8400-e29b-41d4-a716-446655440099",
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    { "id": "a1b2c3", "text": "Bug fixes" },
    { "id": "d4e5f6", "text": "New features" },
    { "id": "g7h8i9", "text": "Performance improvements" }
  ],
  "selectionType": "single",
  "status": "active",
  "createdAt": 1699564800000
}
Save the id (the poll ID) and the options[].id values — you need them to submit votes.

​
Vote on a Poll

POST https://api.zenzap.co/v2/polls/{pollId}/votes
Use the poll id from the create response as the pollId path parameter, and one of the options[].id values as optionId. 
{
  "optionId": "a1b2c3"
}
Response — 201 Created: 
{
  "id": "770e8400-e29b-41d4-a716-446655440099_a1b2c3_b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6",
  "attachmentId": "770e8400-e29b-41d4-a716-446655440099",
  "optionId": "a1b2c3",
  "createdAt": 1699564800000
}
Each {pollId, optionId, voter} combination is idempotent — re-submitting the same vote is a no-op.

​
Delete a Vote

DELETE https://api.zenzap.co/v2/polls/{pollId}/votes/{voteId}
Use the id from the vote creation response as voteId. Response — 204 No Content (empty body on success) 404 is returned if the vote is not found.

​
Request Fields

​
POST /v2/polls

FieldTypeRequiredDescription
topicIdstring (UUID)YesTopic to post the poll in. The bot must be a member.
questionstringYesPoll question / title. Max 500 characters.
optionsstring[]YesAnswer option texts. Min 2, max 10. Each option max 1000 characters.
selectionType"single" | "multiple"YesWhether voters may choose one or multiple options.
anonymousbooleanNoIf true, voter identities are hidden. Anonymous polls do not support voting via the API.

​
POST /v2/polls//votes

FieldTypeRequiredDescription
optionIdstringYesThe 6-character ID of the option to vote for. Use the id from the poll’s options array.

​
Constraints

ConstraintBehavior
Anonymous pollsVoting via the API is not supported (400 anonymous polls are not supported)
Closed pollsVotes are rejected (400 poll is closed)
Not a memberBot must be a member of the topic (403)
selectionType: "single"Each voter can vote for one option
selectionType: "multiple"Each voter can vote for any number of options
Duplicate votesIdempotent — same {pollId, optionId, voter} combination is a no-op

​
Webhook Events

Zenzap fires webhook events when votes are cast or retracted on polls in topics your bot is a member of:
EventFired when
poll_vote.createdA member votes on a poll
poll_vote.deletedA vote is retracted (by a user in the app or via DELETE /v2/polls/{pollId}/votes/{voteId})
See Webhook Events for full payload details.