Results posting

The responses are submitted, the results are collected, and the visualizations are generated. It is time to publish the results.

This guide explains how to automatically publish the results to a Telegram channel. For each teacher, the bot creates a post containing the generated visualization together with a caption including the teacher's name, role and courses. Responses to open-ended questions are then published as comments under the post, grouped by question type and split into batches of four comments per message.

Prerequisites

Before running the posting bot, you need to create a Telegram bot.

1. Create a new bot using BotFather and obtain its API token.
2. Create (or choose) a Telegram channel where the survey results will be published.
3. Add the bot to the channel and grant it administrator permissions so it can publish posts.
4. Create a Telegram group, link it to the channel as its discussion group and add bot there as admin.

The discussion group is required because the Telegram Bot API does not allow bots to publish comments directly under channel posts. Instead, comments are posted by bot by sending messages to the linked discussion group, where they automatically appear as comments to the corresponding channel post.

Running the posting bot

The recomended way to run the posting bot is as a Docker container, which makes it easy to run in any environment (e.g. a local machine or a cloud VM). For convenience, the repository also provides a docker-compose.yml configuration for local use. It automatically mounts the data directory and the bot_cfg.json configuration file into the container.

Before starting the bot, make sure the mounted data directory contains:

• the filtered aggregated survey results;
• the directory with generated visualizations;
• all teacher information JSON files collected during Step 1: Information collection;
• if available, file with links to previous surveys.

To start the bot, run:

docker compose up

To run it in the background, add the -d flag:

docker compose up -d

If you modify the bot source code, rebuild the Docker image before starting it again.

After the bot finishes publishing all results, you should manually stop the Docker Compose process. Otherwise, it may restart automatically on system reboot or container restart policies. While no duplicate posts will be published (thanks to the persistent state file that tracks progress), stopping the container is still necessary to avoid unnecessary resource usage and unintended reruns of the bot.

Configuration

The bot is configured through a bot_cfg.json file located in the repository root.

Example:

{
    "TG_TOKEN": "",
    "channel_id": "@ipt_bee",
    "teachers_info_files": [
        "data/FI-81.json",
        "data/FI-82.json",
        ...
        "data/FF-82.json"
    ],
    "survey_results": "data/2526_2/filtered_agg_results.parquet",
    "viz_folder": "data/2526_2/viz",
    "prev_surveys_links": "data/prev_links.json",
    "start_time": "2025-02-11T17:00:00.000Z",
    "interval_min": 15,
    "working_hours": {
        "min": 16,
        "max": 21
    },
    "n_batch": 4,
    "pers_state_file": "data/2526_2/pers_state.json",
    "col2desc": {
        "Які позитивні риси є у викладача (такі, що можна порекомендувати іншим викладачам)?": "Які позитивні риси є у викладача?",
        "drawbacks_merged": [
            "Які недоліки є у викладанні?",
            "Які шляхи їх вирішення ви бачите?"
        ],
        "Поради для студентів. Що краще робити (чи навпаки, не робити) для побудови гарних відносин із викладачем, які характерні особливості є у викладача, про які ви вважаєте варто знати тим, хто буде у нього вчитись?": "Поради для студентів.",
        "Відкритий мікрофон. Усе, що ви хочете сказати про викладача, але що не покрив жоден інший пункт": "Відкритий мікрофон."
    },
    "col2emoji": {
        "Які позитивні риси є у викладача (такі, що можна порекомендувати іншим викладачам)?": "💚",
        "drawbacks_merged": [
            "🔴",
            "➡️"
        ],
        "Поради для студентів. Що краще робити (чи навпаки, не робити) для побудови гарних відносин із викладачем, які характерні особливості є у викладача, про які ви вважаєте варто знати тим, хто буде у нього вчитись?": "🤝",
        "Відкритий мікрофон. Усе, що ви хочете сказати про викладача, але що не покрив жоден інший пункт": "📢"
    }
}

Configuration fields

• TG_TOKEN — Telegram bot token obtained from @BotFather.

• channel_id — tag or identifier of the Telegram channel where results will be published.

• teachers_info_files — list of teacher information files collected during Step 1: Information collection.

• survey_results — path to the filtered aggregated survey results.

• viz_folder — directory containing generated visualization images.

• prev_surveys_links — JSON file storing links to posts from previous survey iterations generated by gather_links_to_previous_surveys.py

• start_time — date and time when the bot should begin publishing posts.

• interval_min — interval (in minutes) between consecutive teacher posts.

• working_hours — hours during which the bot is allowed to publish. If the next scheduled post falls outside this interval, it is postponed until the next allowed time.

• n_batch — maximum number of open-ended responses included in a single comment. Additional responses are split into subsequent comments.

• pers_state_file — path to the persistent state file used by the bot to resume posting after restarts without duplicating already published content.

• col2desc — mapping from dataset column names to the titles displayed above each group of open-ended responses in the comments. The special key drawbacks_merged combines two related questions into a single section.

• col2emoji — emoji shown alongside each section title in the comments. Its structure mirrors col2desc, including support for merged question groups such as drawbacks_merged.

Important recommendations

1. Test run (staging environment)

It is strongly recommended to perform a full test run before publishing results to the official channel.

One or two days before the official release, create a staging Telegram channel and a corresponding discussion group, then run the bot there to validate that everything works correctly end-to-end.

⚠️ Important: to switch to staging mode, update channel_id in bot_cfg.json to point to the staging channel.

This step helps to:

• verify that visualizations are rendered correctly,
• check formatting of captions and comments,
• detect configuration or data issues before the official run,
• ensure the bot behaves as expected in real conditions.

2. Pre-publication announcement

Before publishing results, make a dedicated post in the official channel explaining the survey. The post should include:

• who conducted the survey;
• how it was conducted (methodology, briefly but clearly);
• when and from whom responses were collected;
• which questions were included (with full descriptions of each question);
• the full list of teachers who did not pass the response threshold;
• a link to the raw dataset (to be published after completion of result posting);
• optionally, a link to this repository :)

3. Post-publication message

After all results have been published, send a final message thanking participants for their responses.

This message should also include a link to an anonymous feedback form for improving future surveys.