aiogram-lambda-template

KO | EN

gitlite — search

#javascript #typescript #llm #go #docker #nodejs #cli #kubernetes #vue #security #pytorch #mcp #ios #openai

aiogram-lambda-template

(★ 16)

Production-grade serverless Telegram bot (aiogram) with Lambda, API Gateway, env-managed config, and streamlined DX for fast iteration as plus small bots can run for free forever 🚀

aiogram-lambda-template 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Telegram Bot AWS Lambda Template

A robust and scalable template for creating Telegram bots deployed on AWS Lambda using `aiogram`. This template provides a solid foundation with a clean project structure, local development support, and a flexible, automated deployment pipeline.

## Features

- Asynchronous with `aiogram` 3.x
- Serverless on AWS Lambda (API Gateway webhook)
- Clean project structure (`core`, `handlers`, `utils`)
- Local development via polling (`main.py`)
- Automated deployment script with optional manual upload (`deploy.sh`)
- Secure webhook management via Lambda "Test" or deploy script
- Environment-based configuration (`.env.dev`, `.env.prod`)
- Makefile shortcuts for common tasks

## Project Structure

```
.
├── core/               # Core application logic (bot instance, config)
├── handlers/           # Message and command handlers
├── states/             # FSM states (if used)
├── keyboards/          # Reply/inline keyboards
├── utils/              # Utility functions (e.g., logging)
├── docs/imgs/          # Documentation images
├── .env.example        # Example environment file
├── .gitignore
├── README.md
├── deploy.sh           # Automated deployment script
├── lambda_function.py  # AWS Lambda handler entry point
├── main.py             # Local development (polling)
├── makefile            # Makefile for common commands
└── requirements.txt
```

## Prerequisites

- Python 3.11+ (Lambda runtime 3.11 or 3.13)
- AWS account with the [AWS CLI](https://aws.amazon.com/cli/) configured
- A Telegram Bot Token from [@BotFather](https://t.me/BotFather)

## Quickstart

- Local dev (polling):
  ```bash
  python -m venv .venv && source .venv/bin/activate
  make install-req
  cp .env.example .env.dev  # fill BOT_TOKEN for dev
  make run                  # starts bot locally
  ```
- Deploy to Lambda (interactive):
  ```bash
  cp .env.example .env.prod  # fill BOT_TOKEN, LAMBDA_URL, SECRET_KEY
  make deploy                # choose auto or manual upload
  ```

## Configuration

This template uses separate env files for dev and prod.

- `.env.dev` (local polling):
  ```env
  BOT_TOKEN="your_development_bot_token"
  ```
- `.env.prod` (deployed Lambda):
  ```env
  BOT_TOKEN="your_production_bot_token"
  LAMBDA_URL="https://<api-id>.execute-api.<region>.amazonaws.com/<stage>/webhook"
  SECRET_KEY="a_very_long_and_random_secret"
  ```
  - LAMBDA_URL must be the full public API Gateway URL that maps to your Lambda webhook route, including `/webhook`.
  - SECRET_KEY is used to authorize management commands (e.g., set/delete webhook) via Lambda.

## Local Development

To run the bot locally using long polling, simply run:

```bash
make run
```

This uses `.env.dev` and starts polling via `main.py`.

## Deployment to AWS Lambda

The `deploy.sh` script handles packaging and (optionally) deployment.

1. Run the script:
   ```bash
   make deploy
   ```
2. The script will create `deployment.zip`, then ask:
   "Do you want to deploy to AWS now? (y/n)"
   - Press `y` for automated deployment:
     1. Uploads code to Lambda
     2. Updates Lambda environment variables using prod `.env` credentials
     3. Prompts to set the webhook via a secure Lambda invocation
   - Press `n` for manual deployment:
     - `deployment.zip` is left in the project directory for manual upload in the AWS Console

### Create Lambda and API Gateway (AWS Console)

1. Go to Lambda Functions and click Create function
   - https://us-east-1.console.aws.amazon.com/lambda/home?region=us-east-1#/functions
   - Give the function a name and choose Python 3.11+ (e.g., Python 3.13)
   - ![Create Lambda](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/create-lambda.png)
2. Increase timeout and memory in Configuration if needed
   - ![Edit memory/timeout](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/edit-memory.png)
3. Add a trigger: API Gateway → Create new API
   - Choose a deployment stage (e.g., `dev`)
   - Use an open security mode for simplicity (you can harden later)
   - ![Add trigger](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/refactor-1.png)
4. In API Gateway, create a route `/webhook`
   - ![Create route](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/route.png)
5. Attach the Lambda integration to that route
   - ![Attach integration](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/attach-integration.png)
6. Copy the final webhook URL from API Gateway triggers
   - Format: `https://<api-id>.execute-api.<region>.amazonaws.com/<stage>/webhook`
   - ![Webhook endpoint](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/webhook-endpoint.png)
7. Add environment variables to Lambda → Configuration → Environment variables
   - Set `BOT_TOKEN`, `LAMBDA_URL`, `SECRET_KEY`
   - ![Environment variables](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/env1.png)
8. Upload the deployment package
   - Click "Upload from" and select `deployment.zip`
   - ![Upload from](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/upload-from.png)
9. Set the webhook (two options):
   - Using Lambda Test (manual):
     - Open the Test tab → Create an event with payload:
       ```json
       {
         "command": "set_webhook",
         "secret": "your_very_secret_key_here"
       }
       ```
     - Click Test
     - ![Invoke test](https://raw.githubusercontent.com/aoulaa/aiogram-lambda-template/main/docs/imgs/test.png)
   - Using the deploy script (automated):
     - When prompted, choose to set the webhook → it will invoke the Lambda with a secure payload
10. Wait up to a few minutes for the webhook to propagate, then send `/start` to your bot.

## Manual Webhook Management

You can also manage the webhook at any time via the Lambda Test tab using the same JSON payload as above, or via the AWS CLI:

```bash
aws lambda invoke \
  --function-name <your-function-name> \
  --payload '{"command":"set_webhook","secret":"<SECRET_KEY>"}' \
  --cli-binary-format raw-in-base64-out \
  --region <region> \
  response.json
```

To delete the webhook, use `"command":"delete_webhook"`.

## Troubleshooting

- Event loop is closed (Lambda):
  - The template uses a safe pattern that closes the bot session after each invocation in `lambda_function.py`. Ensure your deployment uses the latest version.
- 401 Unauthorized from Telegram:
  - Check `BOT_TOKEN` in Lambda env vars (Configuration → Environment variables).
- 403 when setting webhook:
  - Ensure `LAMBDA_URL` is the full API Gateway URL including `/webhook` and that API Gateway route is deployed.
- 502/Integration errors in API Gateway:
  - Re-check that the route is integrated with the correct Lambda in the same region and stage is deployed.
- No messages arriving:
  - Confirm webhook is set (`getWebhookInfo` via Bot API), and view CloudWatch logs (Lambda → Monitor → Logs).

## Security Notes

- Never commit secrets. `.gitignore` excludes `.env` files and build artifacts (`build`, `deployment.zip`).
- Rotate your `BOT_TOKEN` if it is ever exposed.
- Choose a strong, random `SECRET_KEY` and keep it only in Lambda env or `.env.prod` locally.

## Makefile Commands

- `make install-req` — Installs dependencies from `requirements.txt`
- `make run` — Runs the bot locally via polling
- `make deploy` — Builds `deployment.zip` and interactively deploys/sets webhook

aiogram-lambda-template

aiogram-lambda-template 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

aiogram-lambda-template

aiogram-lambda-template 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README