For AI agents: markdown of this page — /docs-content-en/polls/create.md documentation index — /llms.txt

Create a chat poll

POST /v1/chats/:dialogId/polls

Creates a message containing one question and 2–10 answers. A Feed post cannot have a poll added through the API.

Scope: vote; additionally im for a user ID or me. Key restrictions: Polls.

Parameters

Parameter Type Required Default Description
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionchatN, a positive user ID or me. Chat IDs: chat discovery; user IDs: employees

Request body

Field Type Required Default Description
Fieldquestion Typestring Requiredyes Default— DescriptionNon-empty question; whitespace alone is invalid
Fieldanswers Typestring[] Requiredyes Default— Description2 to 10 non-empty strings
Fieldanonymous Typeboolean Requiredno Defaultfalse DescriptionHide voter identities from everyone
FieldmultipleChoice Typeboolean Requiredno Defaultfalse DescriptionAllow multiple choices
FieldallowRevote Typeboolean Requiredno Defaultfalse DescriptionAllow revoting
FieldidempotencyKey Typestring Requiredno Defaultnew UUID DescriptionUUID only. Retry with the same key and unchanged body; use a new key for a new poll

Duplicate protection depends on the Bitrix24 version. A supported version returns the existing poll on key reuse, but does not compare bodies. After 502 POLL_CREATE_OUTCOME_UNKNOWN, inspect the chat first. The platform never automatically replays the write.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat5/polls" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "When?", "answers": ["Now", "Later"], "anonymous": true, "multipleChoice": true, "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat5/polls" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "When?", "answers": ["Now", "Later"], "anonymous": true, "multipleChoice": true, "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat5/polls', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"question": "When?", "answers": ["Now", "Later"], "anonymous": true, "multipleChoice": true, "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}),
})
const result = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat5/polls', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"question": "When?", "answers": ["Now", "Later"], "anonymous": true, "multipleChoice": true, "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}),
})
const result = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.messageId Typenumber DescriptionID of the created or previously created message
Fielddata.voteId Typenumber DescriptionBitrix24 poll number; not pollId
Fielddata.poll Typeobject | null DescriptionPoll object. null if the read after publication failed

Response example

Illustrative response based on the normalizer and test fixtures; not a live Bitrix24 response.

HTTP 201: the message was published, but the subsequent read failed. Do not create it again; find the attachment using messageIds.

JSON 
{
  "success": true,
  "data": {
    "messageId": 42,
    "voteId": 8,
    "poll": null
  }
}

Errors

HTTP Code Cause and action
HTTP400 CodeINVALID_PARAMS Cause and actionInvalid ID or request parameter
HTTP401 CodeTOKEN_MISSING Cause and actionNo Bitrix24 user session
HTTP403 CodeSCOPE_DENIED Cause and actionRequired scope is missing
HTTP403 CodeCOWORK_READONLY Cause and actionOperation forbidden for a Cowork portal-readonly key
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY Cause and actionThe key permits reads only
HTTP403 CodeCHAT_ACCESS_DENIED Cause and actionChat access denied
HTTP403 CodePOLL_ACCESS_DENIED Cause and actionBitrix24 denied access to the personal chat while resolving it; no poll was sent
HTTP404 CodeCHAT_NOT_FOUND Cause and actionThe personal chat could not be resolved
HTTP409 CodePOLL_CREATE_IN_PROGRESS Cause and actionCreation with this key is still in progress; inspect the chat first
HTTP409 CodeIDEMPOTENCY_KEY_CONFLICT Cause and actionKey already used by another user or in another chat
HTTP422 CodeBITRIX_ERROR Cause and actionBitrix24 rejected the request, for example because the method is unavailable in this version
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED Cause and actionThe user behind me could not be resolved; no poll was sent
HTTP502 CodePOLL_CREATE_OUTCOME_UNKNOWN Cause and actionOutcome unknown: inspect the chat first

Other authentication refusals, limits and shared errors: error codes.

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid poll parameters."
  }
}