ZEzenzap
Polls

Create a poll

Create a poll in a topic. The bot must be a member of the topic.

Polls are sent as messages. Each option text is stored server-side with a server-generated 6-character ID — use those IDs when submitting votes.

Anonymous polls (anonymous: true) do not support voting via the API.

post/v2/polls

Request

Headers

X-Signaturestring
Example:a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6

HMAC signature of the request for authentication and replay protection.

Required only when authenticating with a static API key. If you are using an OAuth access token (issued by POST /oauth/token), omit this header — the JWT carries all the authentication and integrity guarantees.

Replay Protection: The signature includes a timestamp to prevent replay attacks. Requests with timestamps older than 5 minutes are rejected.

The signature payload differs by HTTP method:

  • POST/PUT/PATCH/DELETE: HMAC-SHA256 of {timestamp}.{body}
  • GET: HMAC-SHA256 of {timestamp}.{uri}

The signature is calculated as:

  1. Get the current Unix timestamp in milliseconds
  2. Determine the payload:
    • For POST/PUT/PATCH/DELETE: Use {timestamp}.{body} where body is the request body
    • For GET: Use {timestamp}.{uri} where uri is the full request URI (e.g., /v2/members?limit=10)
  3. Calculate HMAC-SHA256 of the combined payload using your API secret
  4. Hex-encode the output
  5. Include the timestamp in the X-Timestamp header

Example for GET request to /v2/members?limit=10:

timestamp = 1699564800000
payload = "1699564800000./v2/members?limit=10"
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

Example for POST request with body {"topicId":"123","text":"Hello"}:

timestamp = 1699564800000
payload = '1699564800000.{"topicId":"123","text":"Hello"}'
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
X-Timestamp: 1699564800000

For multipart/form-data requests, sign the exact raw request body bytes (including boundaries and file bytes) as transmitted.

X-Timestampinteger
Example:1699564800000

Unix timestamp in milliseconds when the request was created. Used for replay protection — requests older than 5 minutes are rejected.

Required only when authenticating with a static API key. Omit when using an OAuth access token.

Request body

topicIdstring uuid required

ID of the topic to post the poll in. The bot must be a member.

questionstring required

The poll question / title.

optionsstring[] required

Poll answer options. Each item is the display text; IDs are generated server-side.

selectionType'single' | 'multiple' required

Whether voters may select one or multiple options:

  • single: one choice allowed
  • multiple: any number of choices allowed
anonymousboolean

If true, voter identities are hidden. Anonymous polls do not support voting via the API.

Example request

{
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    "Bug fixes",
    "New features",
    "Performance improvements"
  ],
  "selectionType": "single"
}

Response

Poll created successfully. The id field is the poll ID — use it as {pollId} when calling POST /v2/polls/{pollId}/votes.

idstring uuid

The poll ID. Use this as the pollId path parameter when voting.

topicIdstring uuid

ID of the topic the poll was posted in.

questionstring

The poll question.

selectionType'single' | 'multiple'
status'active' | 'closed'

Current poll status.

anonymousboolean

Whether the poll is anonymous.

createdAtinteger

Creation timestamp in milliseconds.

Example response

{
  "id": "770e8400-e29b-41d4-a716-446655440099",
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    {
      "id": "a1b2c3",
      "text": "Bug fixes"
    }
  ],
  "selectionType": "single",
  "status": "active",
  "createdAt": 1699564800000
}

Changes

No recorded changes to this operation across all 1 revision of this API.