Для AI-агентов: markdown этой страницы — /docs-content/polls/create.md индекс документации — /llms.txt

Создать опрос в чате

POST /v1/chats/:dialogId/polls

Создаёт сообщение с одним вопросом и 2–10 ответами. Опрос к посту Ленты через API не добавляется.

Скоуп: vote, для ID пользователя или me дополнительно im. Ограничения ключей — Опросы.

Параметры

Параметр Тип Обяз. По умолч. Описание
ПараметрdialogId (path) Типstring Обяз.да По умолч.— ОписаниеchatN, положительный ID пользователя или me. ID чата — из поиска чатов, ID пользователя — из списка сотрудников

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
Полеquestion Типstring Обяз.да По умолч.— ОписаниеНепустой вопрос, строка из одних пробелов недопустима
Полеanswers Типstring[] Обяз.да По умолч.— ОписаниеОт 2 до 10 непустых строк
Полеanonymous Типboolean Обяз.нет По умолч.false ОписаниеСкрыть личности участников от всех
ПолеmultipleChoice Типboolean Обяз.нет По умолч.false ОписаниеРазрешить несколько вариантов
ПолеallowRevote Типboolean Обяз.нет По умолч.false ОписаниеРазрешить переголосование
ПолеidempotencyKey Типstring Обяз.нет По умолч.новый UUID ОписаниеТолько UUID. Для повтора — тот же ключ и неизменённое тело, для нового опроса — новый ключ

Защита от дублей зависит от версии портала. Поддерживающая версия возвращает существующий опрос при повторе ключа, но не сравнивает тела. После 502 POLL_CREATE_OUTCOME_UNKNOWN сначала проверьте чат. Платформа не повторяет запись автоматически.

Примеры

curl — личный ключ

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

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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"], "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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"], "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}),
})
const result = await res.json()

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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"], "allowRevote": true, "idempotencyKey": "3f2b8c1e-6a4d-4f7b-9c2e-1d5a7b9e0c4f"}),
})
const result = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata.messageId Типnumber ОписаниеID созданного или ранее созданного сообщения
Полеdata.voteId Типnumber ОписаниеНомер опроса Битрикс24, не pollId. При повторе с тем же idempotencyKey приходит новое число, которое не находит ни один опрос. Номер опроса — в data.poll.voteId
Полеdata.poll Типobject | null ОписаниеОбъект опроса. null, если чтение после публикации не удалось. Сообщение при этом уже опубликовано: не создавайте его заново, найдите прикрепление через поиск опросов по messageIds

Пример ответа

HTTP 201:

JSON 
{
  "success": true,
  "data": {
    "messageId": 44295,
    "voteId": 33,
    "poll": {
      "id": 25,
      "voteId": 33,
      "source": { "type": "chatMessage", "messageId": 44295 },
      "status": "active",
      "anonymous": false,
      "allowRevote": true,
      "resultsHidden": false,
      "resultsVisible": false,
      "votersCount": null,
      "questions": [
        {
          "id": 35,
          "text": "When?",
          "multipleChoice": false,
          "required": false,
          "votesCount": null,
          "answers": [
            { "id": 85, "text": "Now", "votesCount": null, "percent": null, "voters": [], "votersComplete": false },
            { "id": 87, "text": "Later", "votesCount": null, "percent": null, "voters": [], "votersComplete": false }
          ]
        }
      ],
      "myVote": { "voted": false, "answerIds": [] },
      "permissions": { "canVote": true, "canRevote": true, "canManage": true }
    }
  }
}

Пример ответа при ошибке

400 — передан один вариант ответа:

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

Ошибки

HTTP Код Причина и действие
HTTP400 КодINVALID_PARAMS Причина и действиеНеверный ID, вопрос или набор ответов
HTTP401 КодTOKEN_MISSING Причина и действиеНет пользовательской сессии Битрикс24
HTTP403 КодSCOPE_DENIED Причина и действиеНет скоупа vote либо, для ID пользователя или me, скоупа im
HTTP403 КодCOWORK_READONLY Причина и действиеОперация запрещена для ключа Коворка «портал только для чтения»
HTTP403 КодWRITE_BLOCKED_READONLY_KEY Причина и действиеКлюч разрешает только чтение
HTTP403 КодCHAT_ACCESS_DENIED Причина и действиеНет доступа к чату
HTTP403 КодPOLL_ACCESS_DENIED Причина и действиеБитрикс24 отказал в доступе к личному диалогу при его поиске, опрос не отправлялся
HTTP404 КодCHAT_NOT_FOUND Причина и действиеНе удалось определить личный диалог
HTTP409 КодPOLL_CREATE_IN_PROGRESS Причина и действиеСоздание с этим ключом ещё выполняется, сначала проверьте чат
HTTP409 КодIDEMPOTENCY_KEY_CONFLICT Причина и действиеКлюч уже использован другим пользователем или в другом чате
HTTP422 КодBITRIX_ERROR Причина и действиеБитрикс24 отклонил запрос, например метод недоступен в этой версии
HTTP502 КодME_ALIAS_RESOLUTION_FAILED Причина и действиеНе удалось определить пользователя для me, опрос не отправлялся
HTTP502 КодPOLL_CREATE_OUTCOME_UNKNOWN Причина и действиеЗапрос ушёл в Битрикс24, но ответа нет: таймаут, обрыв соединения или ошибка сервера портала. Сообщение могло появиться — сначала проверьте чат, повторяйте с тем же idempotencyKey и неизменённым телом

Другие отказы авторизации, лимиты и общие ошибки — Ошибки.

Смотрите также