Перейти к содержанию
10 минут чтения
Тема: Практика PHP · Опросы · Викторины

Как создать опрос или викторину в Telegram-боте и обработать ответы

Для примера учебный центр предложит выбрать время занятия, а затем проведёт короткую викторину. Разберём создание нативного опроса Telegram, связь ответа с участником, изменение голоса и закрытие. Для внутренней статистики будем хранить текущее состояние ответа, а не прибавлять единицу на каждое входящее событие.

Выбираем анонимность и правила голосования

Обычный опрос regular подходит для выбора времени. Quiz добавляет правильные ответы и пояснение. Заранее решите, нужны ли результаты конкретного ученика: анонимный опрос даёт общую статистику, но не позволяет составить список ответов по Telegram user_id.

Для персонального учёта бот должен сам отправить неанонимный опрос. Чужой опрос, просто присланный пользователем в чат с ботом, не становится вашим источником индивидуальных голосов. В allowed_updates обработчика включите poll и poll_answer, сохранив другие нужные типы обновлений.

Примеры ниже используют текущий Telegram Bot API и PHP 8.3+ для локальной обработки. Параметры JSON отправляйте вашим настроенным API-клиентом. Перед реальным запуском проведите тест в отдельном личном чате или группе: доступность конкретного режима может зависеть от типа чата.

В нашем сценарии варианты после создания не добавляются, их порядок не перемешивается. Это позволяет сопоставлять option_ids с неизменным массивом вариантов. Для редактируемых опросов потребуется учитывать persistent_id вариантов вместо предположения, что индекс всегда обозначает один ответ.

Создаём опрос для выбора времени

JSON · параметры sendPoll
{
  "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, оставьте его в надёжном входящем журнале и повторите сопоставление после сохранения, вместо удаления события.

Делаем небольшую викторину

JSON · параметры sendPoll для викторины
{
  "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 · poll-answer.php
<?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 для этого метода не заменяет адрес сообщения.

JSON · параметры stopPoll
{"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.