AWS Telegram Chatbot Infrastructure

This project deploys a Telegram chatbot on AWS using Infrastructure as Code (Terraform). It provisions S3 buckets for storing archived chat history, DynamoDB tables for managing user sessions, Lambda for serverless processing, and API Gateway for real-time webhook integration with Telegram.

⚠️ Status: Currently in development. Ollama AI integration (backend models) is not yet implemented. Session management, commands, archive features, and Telegram connectivity are fully functional.

Overview

This project creates a serverless Telegram bot running on AWS. When users send messages to the bot, Telegram forwards them to an API Gateway endpoint, which triggers a Lambda function to process the message and respond.

Key Features:

✅ Real-time message handling via API Gateway webhook
✅ User session creation and management
✅ Command handling (/help, /newsession, /listsessions, /switch, /history, /echo)
✅ Archive system (/archive, /listarchives, /export, file import)
✅ DynamoDB for live session storage
✅ S3 for archived session storage
⏳ Ollama AI integration (planned for next phase)

Architecture

┌─────────────┐      ┌─────────────────┐      ┌────────────────┐
│   Telegram  │─────▶│   API Gateway   │─────▶│     Lambda     │
│    User     │◀─────│   (webhook)     │◀─────│  (handler.py)  │
└─────────────┘      └─────────────────┘      └────────────────┘
                                                      │
                              ┌───────────────────────┴───────────────────────┐
                              ▼                                               ▼
                     ┌─────────────────┐                             ┌─────────────────┐
                     │    DynamoDB     │                             │       S3        │
                     │ (active sessions)│                             │ (archived chats)│
                     └─────────────────┘                             └─────────────────┘

Flow:

User sends a message to the Telegram bot
Telegram POSTs the update to API Gateway webhook URL
API Gateway triggers Lambda function
Lambda processes the message (command or chat)
Active session data is stored/retrieved from DynamoDB
Archived sessions are stored in S3
Lambda sends response back to Telegram

Features

Bot Commands

Command	Purpose	Status
`/start` or `/hello`	Initialize and greet user	✅ Working
`/help`	Show available commands	✅ Working
`/newsession`	Create a new chat session	✅ Working
`/listsessions`	List all user sessions	✅ Working
`/switch <number>`	Switch to a different session	✅ Working
`/history`	Show recent messages in session	✅ Working
`/archive`	List sessions available to archive	✅ Working
`/archive <number>`	Archive a specific session to S3	✅ Working
`/listarchives`	List archived sessions	✅ Working
`/export <number>`	Export archive as JSON file	✅ Working
Send JSON file	Import archive from file	✅ Working
`/status`	Check bot status	✅ Working
`/echo <text>`	Echo back text (test command)	✅ Working
Chat messages	Send to AI model	⏳ Not implemented

Prerequisites

AWS Academy Learner Lab access (or AWS account)
Terraform >= 1.0.0
AWS CLI configured with credentials
Python 3.9+ with pip
Telegram Bot Token (from @BotFather)

AWS Academy Setup

1. Start the Lab

Open AWS Academy and navigate to "Launch AWS Academy Learner Lab"
Click Start Lab and wait for the status to turn green
Click AWS Details to view credentials

2. Configure AWS CLI

Click Show next to "AWS CLI" in AWS Details and copy the credentials:

# Edit credentials file
nano ~/.aws/credentials

Paste the credentials:

[default]
aws_access_key_id=ASIA...
aws_secret_access_key=...
aws_session_token=FwoGZX...

3. Verify Authentication

aws sts get-caller-identity

4. Get LabRole ARN

aws iam get-role --role-name LabRole --query 'Role.Arn' --output text

Output: arn:aws:iam::ACCOUNT_ID:role/LabRole

Deployment

1. Clone and Configure

git clone https://github.com/Man2Dev/cloud-Ai.git
cd cloud-Ai

# Create configuration file
cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars:

telegram_token = "YOUR_TELEGRAM_BOT_TOKEN"
lab_role_arn   = "arn:aws:iam::YOUR_ACCOUNT_ID:role/LabRole"

2. Build Lambda Package

# Clean previous builds
rm -rf package/ lambda_function.zip

# Create package directory
mkdir -p package

# Install dependencies
pip install -r requirements.txt -t ./package

# Copy handler
cp handler.py package/

3. Deploy with Terraform

# Initialize Terraform
terraform init

# Preview changes
terraform plan

# Deploy
terraform apply -auto-approve

4. Note the Outputs

After deployment, Terraform will output:

api_gateway_url - Your webhook URL
s3_bucket_name - S3 bucket for archives
dynamodb_table_name - DynamoDB table name
lambda_function_name - Lambda function name

Telegram Webhook Setup

Set the Webhook

Replace YOUR_BOT_TOKEN and use the api_gateway_url from Terraform output:

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook?url=YOUR_API_GATEWAY_URL"

Example:

curl "https://api.telegram.org/bot123456:ABC-DEF/setWebhook?url=https://abc123.execute-api.us-east-1.amazonaws.com/prod/webhook"

Verify Webhook

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo"

Expected response:

{
  "ok": true,
  "result": {
    "url": "https://abc123.execute-api.us-east-1.amazonaws.com/prod/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0
  }
}

Test the Bot

Open Telegram and find your bot
Send /start or /help
The bot should respond instantly!

Project Structure

.
├── provider.tf                 # AWS provider configuration
├── main.tf                     # Infrastructure resources (S3, DynamoDB, Lambda, API Gateway)
├── outputs.tf                  # Terraform outputs (URLs, resource names)
├── terraform.tfvars.example    # Example configuration file
├── terraform.tfvars            # Your configuration (gitignored)
├── requirements.txt            # Python dependencies
├── handler.py                  # Lambda function code
├── package/                    # Lambda deployment package (generated)
├── lambda_function.zip         # Zipped Lambda package (generated)
├── .gitignore                  # Git ignore rules
├── LICENSE                     # GPL v3 License
└── README.md                   # This documentation

Data Storage

DynamoDB (Active Sessions)

Table: chatbot-sessions

Attribute	Type	Purpose
`pk`	Number	Telegram user ID (partition key)
`sk`	String	Session identifier (sort key)
`model_name`	String	Selected AI model
`session_id`	String	UUID for the session
`conversation`	List	Array of messages
`is_active`	Number	1 = active, 0 = inactive
`last_message_ts`	Number	Unix timestamp

Global Secondary Indexes:

model_index - Query by model across users
active_sessions_index - Query active sessions

S3 (Archived Sessions)

Bucket: chatbot-conversations-{ACCOUNT_ID}

Structure:

chatbot-conversations-123456789/
└── archives/
    └── {user_id}/
        ├── {session_id_1}.json
        └── {session_id_2}.json

Verification

CLI Verification

# Check Lambda
aws lambda get-function --function-name telegram-bot

# Check DynamoDB
aws dynamodb describe-table --table-name chatbot-sessions

# Check S3
aws s3 ls

# Check API Gateway
aws apigateway get-rest-apis

# View Lambda logs
aws logs tail /aws/lambda/telegram-bot --follow

AWS Console Verification

Access the console through AWS Academy:

Click AWS button (green dot) in Vocareum
Navigate to Lambda, DynamoDB, S3, API Gateway services

Troubleshooting

Authentication Errors

Session tokens expire every few hours
Refresh credentials from AWS Academy → AWS Details

"AccessDenied" for IAM

AWS Academy restricts IAM role creation
Use the pre-existing LabRole via lab_role_arn variable

Lambda Not Responding

Check CloudWatch logs: aws logs tail /aws/lambda/telegram-bot --follow
Verify environment variables are set

Webhook Not Working

Verify API Gateway URL is correct
Test Lambda directly: aws lambda invoke --function-name telegram-bot out.json
Check webhook info: curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

S3 Bucket Name Conflict

Bucket names must be globally unique
The template uses chatbot-conversations-{ACCOUNT_ID} for uniqueness

Cleanup

Remove All Resources

terraform destroy -auto-approve

Remove Telegram Webhook

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/deleteWebhook"

Quick Reference

# Deploy
terraform init && terraform apply -auto-approve

# Get webhook URL
terraform output api_gateway_url

# Set webhook
curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=<URL>"

# Check webhook
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

# View logs
aws logs tail /aws/lambda/telegram-bot --follow

# Test Lambda
aws lambda invoke --function-name telegram-bot out.json && cat out.json

# Destroy
terraform destroy -auto-approve

License

This project is licensed under GNU General Public License v3.0 or later (GPLv3+). See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
scripts		scripts
.env.tfvars		.env.tfvars
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
handler.py		handler.py
main.tf		main.tf
outputs.tf		outputs.tf
provider.tf		provider.tf
requirements.txt		requirements.txt
terraform.tfvars.example		terraform.tfvars.example

License

Man2Dev/cloud-Ai

Folders and files

Latest commit

History

Repository files navigation

AWS Telegram Chatbot Infrastructure

Table of Contents

Overview

Architecture

Features

Bot Commands

Prerequisites

AWS Academy Setup

1. Start the Lab

2. Configure AWS CLI

3. Verify Authentication

4. Get LabRole ARN

Deployment

1. Clone and Configure

2. Build Lambda Package

3. Deploy with Terraform

4. Note the Outputs

Telegram Webhook Setup

Set the Webhook

Verify Webhook

Test the Bot

Project Structure

Data Storage

DynamoDB (Active Sessions)

S3 (Archived Sessions)

Verification

CLI Verification

AWS Console Verification

Troubleshooting

Authentication Errors

"AccessDenied" for IAM

Lambda Not Responding

Webhook Not Working

S3 Bucket Name Conflict

Cleanup

Remove All Resources

Remove Telegram Webhook

Quick Reference

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages