Getting Started with the Air Quality Telegram Bot

This guide will walk you through the process of setting up and running the Air Quality Telegram Bot. The bot fetches air quality data for Phnom Penh and sends periodic updates, including advice and visual cues, to a designated Telegram chat in multiple languages.

Prerequisites

To run this bot, you will need:

• Python 3.6 or higher: Ensure Python is installed on your system. You can download it from python.org↗.
• Required Python Libraries:
  • pyTelegramBotAPI (often installed as telebot)
  • requests

2. Obtain API Keys and Chat ID

The bot relies on external services to function. You will need to obtain specific keys and identifiers:

AirVisual API Key

1. Register for an AirVisual API Key: Go to the IQAir AirVisual API website↗ and sign up for a free API key.
2. Once registered, you should receive your API key, which will be a long string of alphanumeric characters.

Telegram Bot Token

1. Create a New Bot with BotFather:
   • Open Telegram and search for @BotFather.
   • Start a chat with BotFather and send the command /newbot.
   • Follow the instructions to choose a name and a username for your bot.
   • Upon successful creation, BotFather will provide you with an HTTP API Token. This token is crucial for your bot to interact with the Telegram API.

Telegram Chat ID

1. Find your Chat ID: The bot needs to know where to send messages. This can be a personal chat with your bot, a group chat, or a channel.
   • For a private chat with your bot: Start a chat with your newly created bot. Then, send a message to @userinfobot (another Telegram bot) or @getidsbot. It will tell you your Chat ID.
   • For a group chat: Add your bot to a group. Send any message in the group. Then, find a bot like @getidsbot and add it to the same group. It will provide the Chat ID for that group (which typically starts with -).
   • For a channel: Your bot must be an administrator in the channel. The channel ID can also be obtained using @getidsbot.

3. Set Up Environment Variables

It's best practice to keep sensitive information like API keys out of your code. You will set these as environment variables.

You can create a .env file in the root directory of your project to manage these variables. Make sure to install python-dotenv if you plan to use a .env file.

1. Install python-dotenv (if using .env file):

2. Create a .env file: In the root directory of the cloned repository, create a file named .env and add the following lines, replacing the placeholder values with your actual keys and ID:

   Alternatively, you can set these variables directly in your shell environment, which might be preferred for deployment on servers:

   Linux/macOS:

   Windows (Command Prompt):

   Windows (PowerShell):

4. Initialize keys.json

The bot uses a keys.json file to persist the previous Air Quality Index (AQI) value (aqius_prior) between runs, which is essential for detecting air quality changes.

1. Create keys.json: In the root directory of the cloned repository, create a file named keys.json.

2. Add initial content: Populate the file with the following JSON structure:

   This initializes the aqius_prior value to 0, ensuring the bot starts correctly.

5. Installation

Follow these steps to get the repository and install the necessary dependencies:

1. Clone the Repository:

2. Create a Virtual Environment (Recommended):

3. Install Python Dependencies:

4. Prepare the labels directory: The bot sends images based on AQI categories. You need to create a labels directory in the root of your project and place the corresponding image files there. The images should be named according to the AQI categories (e.g., good.png, moderate.png, unhealthy_for_sensitive_groups.png, etc.).

6. Running the Bot

Once all the prerequisites, API keys, environment variables, keys.json, and image files are set up, you can start the bot.

1. Navigate to the project directory (if you're not already there):

2. Run the bot.py script:

The bot will now start running. You should see a "Test message sent!" in your console and, if configured correctly, your bot will send an initial "intell1slt_bot is now online" message to the specified CHAT_ID. It will then begin sending air quality updates according to its Workflow as described in the [Overview] page.