Выбираем анонимность и правила голосования
Обычный опрос regular подходит для выбора времени. Quiz добавляет правильные ответы и пояснение. Заранее решите, нужны ли результаты конкретного ученика: анонимный опрос даёт общую статистику, но не позволяет составить список ответов по Telegram user_id.
Для персонального учёта бот должен сам отправить неанонимный опрос. Чужой опрос, просто присланный пользователем в чат с ботом, не становится вашим источником индивидуальных голосов. В allowed_updates обработчика включите poll и poll_answer, сохранив другие нужные типы обновлений.
Примеры ниже используют текущий Telegram Bot API и PHP 8.3+ для локальной обработки. Параметры JSON отправляйте вашим настроенным API-клиентом. Перед реальным запуском проведите тест в отдельном личном чате или группе: доступность конкретного режима может зависеть от типа чата.
В нашем сценарии варианты после создания не добавляются, их порядок не перемешивается. Это позволяет сопоставлять option_ids с неизменным массивом вариантов. Для редактируемых опросов потребуется учитывать persistent_id вариантов вместо предположения, что индекс всегда обозначает один ответ.
Создаём опрос для выбора времени
{
"chat_id": 123456789,
"question": "Когда удобно провести занятие?",
"options": [{"text": "Вторник, 18:00"}, {"text": "Среда, 19:00"}, {"text": "Суббота, 12:00"}],
"type": "regular",
"is_anonymous": false,
"allows_multiple_answers": false,
"allows_revoting": true,
"shuffle_options": false,
"allow_adding_options": false,
"open_period": 300
}
Опрос открыт пять минут и допускает изменение выбора. Options — массив объектов InputPollOption с text, а не массив строк. Ответ sendPoll содержит Message: сохраните result.chat.id, result.message_id и result.poll.id только после ok=true.
В таблице polls храните bot_id, poll_id, chat_id, message_id, тип, варианты, правила голосования и статус. Poll_id — строка. Он связывает входящие ответы с вашим событием, а chat_id/message_id нужны для stopPoll. Подготовьте локальную операцию создания заранее, чтобы её результат не потерялся между HTTP-ответом и записью БД.
После таймаута sendPoll нельзя уверенно считать, что опрос не создан. Безусловный повтор может показать два опроса. Отметьте неизвестный результат и разберите его до повторной отправки. Если poll_answer пришёл раньше сохранения poll_id, оставьте его в надёжном входящем журнале и повторите сопоставление после сохранения, вместо удаления события.
Делаем небольшую викторину
{
"chat_id": 123456789,
"question": "Какой метод отправляет текстовое сообщение?",
"options": [{"text": "getMe"}, {"text": "sendMessage"}, {"text": "getFile"}],
"type": "quiz",
"is_anonymous": false,
"allows_multiple_answers": false,
"allows_revoting": false,
"correct_option_ids": [1],
"explanation": "sendMessage отправляет текст в указанный чат.",
"open_period": 300
}
В актуальном API правильные варианты передаются массивом correct_option_ids. Индексы начинаются с нуля, поэтому [1] означает второй вариант. Для нашего теста правильный ответ один, выбор тоже один, изменение ответа выключено. Не переносите в этот пример старое имя поля correct_option_id из устаревших руководств.
Сохраните ключ правильных ответов вместе с локальной записью опроса. Для персонального результата сравните нормализованный набор выбранных индексов с этим ключом. Одна викторина Telegram — один вопрос; последовательность урока, несколько вопросов и итоговый балл хранит ваше приложение.
Не используйте текст варианта как ключ результата: формулировка может измениться. Если разрешите несколько правильных вариантов, отдельно определите правило оценивания: полное совпадение набора или частичные баллы. В данном примере оценивается полное совпадение.
Обрабатываем полный снимок ответа участника
Poll_answer содержит poll_id и option_ids. Это текущий выбор, а не прибавка к предыдущему: при смене [0] на [2] старый ответ заменяется. Пустой массив означает отзыв голоса. User может отсутствовать, если ответ связан с voter_chat; такой голос нельзя приписывать выдуманному user_id.
<?php
declare(strict_types=1);
/** @param array<string, mixed> $answer
* @return array{voter_key: string, option_ids: list<int>}|null
*/
function normalizedVote(array $answer, string $pollId, int $optionCount): ?array
{
if (($answer['poll_id'] ?? null) !== $pollId) {
return null;
}
$user = $answer['user']['id'] ?? null;
$chat = $answer['voter_chat']['id'] ?? null;
if (is_int($user) && $chat === null) {
$voter = 'user:'.$user;
} elseif (is_int($chat) && $user === null) {
$voter = 'chat:'.$chat;
} else {
return null;
}
$ids = $answer['option_ids'] ?? null;
if (!is_array($ids) || !array_is_list($ids)) {
return null;
}
foreach ($ids as $id) {
if (!is_int($id) || $id < 0 || $id >= $optionCount) {
return null;
}
}
$ids = array_values(array_unique($ids));
sort($ids, SORT_NUMERIC);
return ['voter_key' => $voter, 'option_ids' => $ids];
}
Функция проверяет форму данных, но право учесть ответ определяется отдельно: poll_id должен относиться к опросу вашего бота, а ученик — к нужной учебной группе, если отчёт ограничен её составом. Voter_key с префиксом chat храните отдельно от личных результатов учащихся.
Заведите poll_votes с UNIQUE(bot_id, poll_id, voter_key). В одной транзакции сохраните обработанный update и замените option_ids целиком. Повтор (bot_id, update_id) не меняет счётчики. Отозванный голос сохраняйте как пустой набор: это позволит отличить отзыв от отсутствия каких-либо событий.
При параллельной обработке более старое событие не должно затереть новое. Для короткого опроса из примера сохраняйте last_update_id возле голоса и обновляйте строку только при большем update_id; проверка и запись выполняются атомарно. Этот порядок относится к потоку конкретного бота. Для долгоживущих процессов учитывайте, что Telegram после длительного отсутствия обновлений может начать новую последовательность update_id.
Счётчики можно пересчитать из текущих наборов. При множественном выборе сумма голосов по вариантам может превышать число участников. Не называйте эту сумму количеством проголосовавших людей.
Получаем общие результаты и закрываем опрос
Update.poll содержит агрегированные сведения: options с voter_count, total_voter_count и is_closed. Он полезен для итоговой карточки и анонимных опросов, но не раскрывает список участников. Не пытайтесь восстановить персональные ответы из изменения общего счётчика.
Опрос примера закроется по open_period. Для ручного завершения вызовите stopPoll с сохранёнными chat_id и message_id. Poll_id для этого метода не заменяет адрес сообщения.
{"chat_id": 123456789, "message_id": 450}
Успешный stopPoll возвращает Poll: сохраните итоговые счётчики и is_closed. После нажатия кнопки администратора сначала проверьте его права на закрытие. Простое наличие callback с номером опроса не даёт такое право.
Не отбрасывайте уже полученные, но ещё не обработанные poll_answer только потому, что успели сохранить is_closed=true. Голос мог быть принят до закрытия, а доставлен позже. Дождитесь обработки входящего журнала, после чего формируйте персональный отчёт. Агрегированный итог Telegram и локальный список ответов полезно сверять, но они не всегда описывают одну аудиторию, если вы исключаете внешних участников.
При таймауте stopPoll результат неизвестен: дождитесь poll с is_closed или повторно выясните состояние предусмотренным вашим обработчиком способом. Не помечайте опрос открытым лишь потому, что подтверждение закрытия не дошло. У Bot API нет универсального getPoll для произвольного poll_id.
Проверяем ответы и итоговую статистику
Создайте неанонимный опрос ботом и сохраните все три идентификатора: chat_id, message_id и poll.id.
Выберите первый вариант, затем третий: в локальной записи остаётся третий, а число участников не растёт.
Отзовите голос, если режим это допускает: сохранится пустой набор.
Повторите один update и поменяйте порядок обработки двух ответов: старый не должен перезаписать новый.
Проверьте анонимный опрос: отчёт содержит общие числа без обещания персональных результатов.
Закройте опрос и обработайте задержанный ответ, затем сверьте итоговый отчёт.
Если ответы не приходят, проверьте is_anonymous, происхождение опроса, allowed_updates и журнал webhook. Общую диагностику доставки смотрите в руководстве по webhook.
При подключении через BotGate параметры sendPoll и stopPoll передаются через API сервиса, а результаты и права участников остаются в вашем приложении. Первичные источники: sendPoll, PollAnswer и stopPoll.