Опросы

Опросы в Ленте через API не создаются: в REST API Битрикс24 создание опроса в Ленте официально не поддерживается. Существующие опросы можно читать и управлять ими. В чате опрос можно создать через API.

Скоуп: vote | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Доступ

Все операции требуют скоуп vote. При создании в личном диалоге, когда dialogId — ID пользователя или me, дополнительно нужен im, для chatN достаточно vote. Права текущего пользователя в Битрикс24 продолжают действовать. Опросом чата управляет автор сообщения, в Ленте нужны права управления постом.

Все четыре GET-операции читают опрос и подписывают пользователя на события Битрикс24, поэтому для ключа Коворка с запретом записи в портал они недоступны. Методы опросов также недоступны через пакетные запросы.

Как найти опрос

В списке постов (GET /v1/posts) выберите записи с hasPoll: true. Затем передайте ID постов в GET /v1/polls?postIds=42.

В сообщениях чата (GET /v1/chats/:dialogId/messages) опрос отмечен полем data.messages[].params.componentId = "VoteMessage". Значение params.componentParams.id — это voteId, номер опроса Битрикс24. Для поиска прикрепления передавайте ID сообщения, а не voteId, в GET /v1/polls?messageIds=42.

В полученном объекте id — идентификатор прикрепления (pollId в путях API). Он отличается от voteId, ID поста и ID сообщения. Если прикрепление не распознано, source может отсутствовать.

Объект опроса

Результаты и анонимность

Итоги закрыты при resultsHidden: true или пока опрос активен, пользователь может голосовать и ещё не голосовал. Исключение — автор опроса, если Битрикс24 сообщает об авторстве: так бывает в опросах чатов на поддерживающих версиях портала. Права управления постом или сообщением итоги не открывают. Автору опроса Ленты скрытые итоги доступны в интерфейсе Битрикс24. При недостающих данных о правах итоги закрываются, а завершённый опрос без скрытия итогов доступен. При resultsVisible: false поля votersCount, questions[].votesCount, questions[].answers[].votesCount и percent равны null, а у ответов voters: [] и votersComplete: false во всех ответах API с объектом опроса.

В анонимном опросе проголосовавших не видно никому, включая автора и администратора: счётчики доступны, если resultsVisible: true. В результатах voters всегда пуст и votersComplete равен false. Для открытого опроса результаты содержат ограниченную выборку участников по каждому ответу, полный список читается отдельной операцией. Счётчики не кэшируются.

Отчёт Excel и ссылки на итоги через API не отдаются. Выгрузить отчёт можно в интерфейсе Битрикс24.

Безопасное выполнение записи

idempotencyKey при создании — только UUID. Повтор с тем же ключом и тем же телом на поддерживающей версии портала возвращает уже созданный опрос в data.poll. Поле data.voteId при повторе приходит новым числом, которое не находит ни один опрос, поэтому номер опроса берите из data.poll.voteId. Новый опрос — новый ключ. Битрикс24 не сравнивает тела: не меняйте вопрос, ответы или настройки при повторе. Если ключ не задан, сервер генерирует новый UUID для каждого запроса. Защита от дублей зависит от версии портала.

Платформа не повторяет записи автоматически. При 502 POLL_CREATE_OUTCOME_UNKNOWN сначала посмотрите чат: сообщение могло появиться. При других 502 …_OUTCOME_UNKNOWN прочитайте опрос и решите, нужна ли повторная запись. Не создавайте новый ключ сразу после неизвестного исхода.

При переголосовании в Ленте, если опрос правят в момент голоса, Битрикс24 может стереть прежний голос — так же, как в интерфейсе. После ошибки проверьте myVote.

Удаление

Отдельного удаления опроса нет. Удалите содержащий его пост или сообщение существующим маршрутом.

Быстрый старт

Прочитать опрос по ID прикрепления:

curl -H "X-Api-Key: YOUR_API_KEY" "https://vibecode.bitrix24.tech/v1/polls/25"

Поля ответа — Получить опрос.

Полный пример

Создать опрос в чате, проголосовать, прочитать итоги и остановить опрос:

const BASE = 'https://vibecode.bitrix24.tech/v1'
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

async function call(method, path, body) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: body ? headers : { 'X-Api-Key': headers['X-Api-Key'] },
    body: body ? JSON.stringify(body) : undefined,
  })
  const json = await res.json()
  if (!json.success) throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`)
  return json
}

// 1. Создать опрос в чате
const created = await call('POST', '/chats/chat5/polls', {
  question: 'When?',
  answers: ['Now', 'Later'],
  idempotencyKey: crypto.randomUUID(),
})
const poll = created.data.poll
console.log('Опрос', poll.id, 'в сообщении', created.data.messageId)

// 2. Проголосовать за первый ответ
const firstAnswer = poll.questions[0].answers[0].id
await call('POST', `/polls/${poll.id}/vote`, { answerIds: [firstAnswer] })

// 3. Прочитать итоги
const results = await call('GET', `/polls/${poll.id}/results`)
for (const answer of results.data.questions[0].answers) {
  console.log(answer.text, answer.votesCount, `${answer.percent}%`)
}

// 4. Остановить опрос
await call('POST', `/polls/${poll.id}/stop`)
const finished = await call('GET', `/polls/${poll.id}`)
console.log('Статус:', finished.data.status)

Справочник эндпоинтов

Коды ошибок

Ошибки опросов

Системные ошибки

Полный список общих ошибок API — Ошибки.

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

• Список постов
• Сообщения
• Поиск чатов
• Пакетные вызовы