Polls

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

Field	Type	Required	Description
`topicId`	string (UUID)	Yes	Topic to post the poll in. The bot must be a member.
`question`	string	Yes	Poll question / title. Max 500 characters.
`options`	string[]	Yes	Answer option texts. Min 2, max 10. Each option max 1000 characters.
`selectionType`	`"single"` \| `"multiple"`	Yes	Whether voters may choose one or multiple options.
`anonymous`	boolean	No	If `true`, voter identities are hidden. Anonymous polls do not support voting via the API.

POST /v2/polls//votes

Field	Type	Required	Description
`optionId`	string	Yes	The 6-character ID of the option to vote for. Use the `id` from the poll’s `options` array.

Constraints

Constraint	Behavior
Anonymous polls	Voting via the API is not supported (`400 anonymous polls are not supported`)
Closed polls	Votes are rejected (`400 poll is closed`)
Not a member	Bot 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 votes	Idempotent — 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:

Event	Fired when
`poll_vote.created`	A member votes on a poll
`poll_vote.deleted`	A vote is retracted (by a user in the app or via `DELETE /v2/polls/{pollId}/votes/{voteId}`)

See Webhook Events for full payload details.

Get Started

Enterprise

FAQ

Guides

Integrations

Create a Poll

Vote on a Poll

Delete a Vote

Request Fields

POST /v2/polls

POST /v2/polls//votes

Constraints

Webhook Events

​Create a Poll

​Vote on a Poll

​Delete a Vote

​Request Fields

​POST /v2/polls

​POST /v2/polls//votes

​Constraints

​Webhook Events

Create a Poll

Vote on a Poll

Delete a Vote

Request Fields

POST /v2/polls

POST /v2/polls//votes

Constraints

Webhook Events