PostFlow Telegram Bot ✍️

A powerful Telegram bot for managing and scheduling social media posts with AI support. Self-hosted, open-source, and easy to deploy with Docker.

✨ Features

✍️ Manual Post Creation - Write your posts directly
🤖 AI-Powered Content - Generate posts with OpenAI GPT
📅 Smart Scheduling - Schedule posts for optimal timing
🌍 Timezone Support - Configure your local timezone for scheduling
🔔 Notifications - Get notified when scheduled posts are published
🧵 Auto Thread Creation - Automatically splits long posts into threads (respects 280 char limit)
🎯 Topic Presets - Save favorite topics for quick AI post generation
🧩 Templates - Reusable content blocks for quick posts
🔒 Secure & Private - Self-hosted, only you have access
🐳 Docker Ready - Easy deployment with docker-compose
📊 Statistics - Track your posting performance
📝 Drafts - Save posts and finish later
📆 Weekly Planning - Plan up to 7 days with multiple slots per day
🗓️ Weekly Calendar View - Review scheduled posts by week
🖼️ Image Posts - Publish posts with a single attached image
💾 Persistent Storage - SQLite database for reliability
🎨 Beautiful UI - Interactive menus and inline buttons
🌐 Localization Ready - i18n support with English fallback

📋 Prerequisites

Docker and Docker Compose installed
A Telegram Bot Token from @BotFather
X Developer Account with API credentials
(Optional) OpenAI API key for AI features

🚀 Quick Start

1. Get Your Telegram User ID

Open a chat with @userinfobot
It replies with your User ID
Copy the number into TELEGRAM_USER_ID

Example reply:

Your user ID: 123456789

2. Get X API Credentials

Go to developer.twitter.com
Create a new app or use existing one
Generate API keys and access tokens
You'll need:

API Key
API Secret
Access Token
Access Token Secret

3. Clone the Repository

git clone https://github.com/artcc/postflow-telegram-bot.git
cd postflow-telegram-bot

4. Configure Environment Variables

Create a .env file from the example:

cp .env.example .env

Edit the .env file with your credentials:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_USER_ID=123456789

# Timezone (required) - Your local timezone for scheduling
# Examples: Europe/Madrid, America/New_York, Asia/Tokyo
TZ=Europe/Madrid

# Twitter/X API Credentials
TWITTER_API_KEY=your_api_key_here
TWITTER_API_SECRET=your_api_secret_here
TWITTER_ACCESS_TOKEN=your_access_token_here
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret_here

# OpenAI API (optional - leave empty to disable AI features)
OPENAI_API_KEY=sk-your-openai-api-key-here

# Database Configuration (default: /data/postflow.db)
DATABASE_PATH=/data/postflow.db

Important: All variables are required except OPENAI_API_KEY (optional). The bot won't start without the required credentials.

Timezone: Use standard timezone names from IANA Time Zone Database (e.g., Europe/Madrid, America/New_York, Asia/Tokyo).

5. Deploy with Docker Compose

The docker-compose.yml configuration:

services:
  postflow-bot:
    image: ghcr.io/artcc/postflow-telegram-bot:latest
    container_name: postflow-bot
    environment:
      # Telegram Bot Configuration
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - TELEGRAM_USER_ID=${TELEGRAM_USER_ID}
      
      # Timezone (required) - e.g., Europe/Madrid, America/New_York
      - TZ=${TZ}
      
      # Twitter/X API Credentials
      - TWITTER_API_KEY=${TWITTER_API_KEY}
      - TWITTER_API_SECRET=${TWITTER_API_SECRET}
      - TWITTER_ACCESS_TOKEN=${TWITTER_ACCESS_TOKEN}
      - TWITTER_ACCESS_TOKEN_SECRET=${TWITTER_ACCESS_TOKEN_SECRET}
      
      # OpenAI API (optional)
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      
      # Database Configuration
      - DATABASE_PATH=${DATABASE_PATH:-/data/postflow.db}
    volumes:
      - ./data:/data  # Database persistence
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Start the bot:

# Start the bot in detached mode
docker-compose up -d

The docker-compose.yml automatically:

Pulls the latest image from GitHub Container Registry
Loads environment variables from .env file
Creates a persistent volume for the database (./data)
Configures automatic restarts
Sets up log rotation

Note: The image is pulled from ghcr.io/artcc/postflow-telegram-bot:latest - no build required!

6. Verify the Bot is Running

# Check container status
docker ps | grep postflow-bot

# View real-time logs
docker logs -f postflow-bot

Expected output:

2026-02-02 10:30:15 - bot.config - INFO - Bot configured for user ID: 123456789
2026-02-02 10:30:15 - bot.config - INFO - Twitter API: Enabled
2026-02-02 10:30:15 - bot.config - INFO - OpenAI API: Enabled
2026-02-02 10:30:15 - bot.main - INFO - Starting PostFlow Telegram Bot...
2026-02-02 10:30:16 - bot.main - INFO - Bot is running... Press Ctrl+C to stop.

Troubleshooting startup:

If you see errors about missing variables, check your .env file
If container exits immediately, check logs: docker logs postflow-bot
Verify all required credentials are set correctly

💬 Using the Bot

Basic Usage

Open Telegram and find your bot
Send /start to verify authorization
Use /menu to access the main menu
Click "✍️ New" to create your first post

Creating Posts

Manual Post

Click "✍️ New" → "✏️ Write Manually"
Type your content
Preview and choose "🚀 Publish Now" or "📅 Schedule"

AI-Generated Post

Click "✍️ New" → "🤖 AI"
If you have topic presets, select one or choose "✏️ Custom Prompt"
For custom: Describe what you want: "Post about Python advantages"
Review generated content
Publish or schedule

Template Post

Click "✍️ New" → "🧩 Templates"
Choose a template
Review the prefilled content
Edit if needed, then publish or schedule

Managing Topic Presets

Topic presets allow you to quickly generate AI posts on your favorite subjects.

Adding Topics

Click "🎯 Topics" in main menu or use /topics
Click "➕ Add Topic"
Enter a topic name (3-30 characters)
- Examples: "Python Programming", "AI & ML", "Tech News"
Topic is saved for quick access (max 10 topics)

Using Topics

Click "✍️ New" → "🤖 AI"
Select a topic preset button
AI generates a professional post about that topic
Review, edit if needed, then publish or schedule

Managing Topics

List Topics: View all your saved topics
Delete Topic: Remove individual topics
Delete All: Clear all topics (with confirmation)

Note: Topics require OpenAI to be configured. Each topic generates unique content every time and is limited to a single post (max 280 characters).

Managing Templates

Click "🧩 Templates" in main menu or use /templates
Add a template (name + content)
List templates to view details
Edit content or delete when needed
Use a template to create a post in one tap

Weekly Plan

Click "✍️ New" → "📆 Plan Week"
Select days (rolling 7-day window)
Choose posts per day (max 3)
Enter time slots for each day
Create each post manually or with AI
Review summary and confirm scheduling

Image Post

Click "✍️ New" → "🖼️ Image"
Send an image with an optional caption (max 280 chars)
Preview and choose "🚀 Publish Now" or "📅 Schedule"

Thread Creation

Posts longer than 280 characters are automatically converted to threads:

Intelligent splitting at sentence boundaries
Automatic numbering (1/3, 2/3, 3/3)
Preview before publishing
All tweets published as connected thread

Scheduling Posts

Create your post (manual or AI)
Choose "📅 Schedule"
Select quick option or custom date:
- ⏰ In 1 hour
- ⏰ In 3 hours
- 📆 Tomorrow 9am
- 📆 Custom date (format: 2026-01-25 18:00)
Post will be published automatically at scheduled time
You'll receive a notification when the post is published

Note: All times are displayed in your configured timezone (TZ environment variable).

Post Notifications

When a scheduled post is published (or fails), you'll receive a notification:

Success notification:

🎉 SCHEDULED POST PUBLISHED
✅ Your scheduled post #123 has been published successfully!
🔗 View on X

Failure notification:

❌ SCHEDULED POST FAILED
⚠️ Your scheduled post #123 could not be published.
📝 Error: [error details]
💡 Check /menu to retry or reschedule.

Managing Scheduled Posts

Click "📅 Scheduled" in main menu
View all pending posts
Click on any post to:
- 👁️ View details
- ✏️ Edit schedule time
- 🗑️ Delete

Weekly Calendar View

Open "📅 Scheduled" in the main menu
Tap "🗓️ Calendar" to see the current week
Navigate weeks with Previous/Next buttons
Review scheduled posts grouped by day and time

Managing Drafts

Click "📝 Drafts" in main menu
Select a draft to preview
Edit, publish, or schedule from the preview

Available Commands

/start - Welcome message and authorization check
/help - Show help information
/menu - Open interactive main menu
/new - New post
/plan - Plan week
/topics - Manage topic presets
/templates - Manage templates
/drafts - List drafts
/scheduled - List scheduled posts
/stats - Show statistics
/status - Check bot and API status
/settings - Show settings
/chatid - Show your Telegram User ID
/author - About the author
/cancel - Cancel current operation

Internationalization

The bot uses your Telegram language_code and falls back to English when a locale is not available.

📊 Statistics & Monitoring

The bot tracks:

Total posts created
Published posts count
Scheduled posts pending
Failed posts (with error details)
Success rate percentage

Access statistics via the "📊 Statistics" button in the main menu or with /status command.

🔧 Architecture

┌─────────────────┐
│  Telegram User  │
└────────┬────────┘
         │
         ▼
┌─────────────────────┐
│  Telegram Bot API   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────────┐
│  PostFlow Bot           │
│  - Handlers             │
│  - Services             │
│  - Database (SQLite)    │
│  - APScheduler          │
└────────┬────────────────┘
         │
         ├──────────────────┐
         │                  │
         ▼                  ▼
┌──────────────┐   ┌──────────────┐
│   X API      │   │  OpenAI API  │
└──────────────┘   └──────────────┘

Project Structure

postflow-telegram-bot/
├── bot/
│   ├── __init__.py
│   ├── config.py              # Configuration & environment variables
│   ├── main.py                # Bot entry point
│   ├── database/
│   │   ├── __init__.py
│   │   ├── models.py          # SQLAlchemy models
│   │   └── database.py        # Database management
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── commands.py        # Command handlers
│   │   ├── callbacks.py       # Button callback handlers
│   │   ├── posts.py           # Post management logic
│   │   └── conversations.py   # Multi-step conversations
│   ├── locales/
│   │   ├── de.json            # UI strings
│   │   ├── en.json            # UI strings
│   │   └── es.json            # UI strings
│   │   ├── fr.json            # UI strings
│   │   └── it.json            # UI strings
│   ├── services/
│   │   ├── __init__.py
│   │   ├── twitter_service.py # X API integration
│   │   ├── openai_service.py  # OpenAI API integration
│   │   ├── scheduler_service.py # APScheduler management
│   │   ├── post_service.py    # Post business logic
│   │   ├── topic_service.py   # Topic presets management
│   │   └── template_service.py # Templates management
│   └── utils/
│       ├── __init__.py
│       ├── auth.py            # Authorization helpers
│       ├── formatting.py      # Text formatting utilities
│       ├── i18n.py            # Localization helpers
│       └── keyboards.py       # Telegram keyboard builders
├── data/                      # SQLite database (volume)
├── .env                       # Environment variables (not in git)
├── .env.example               # Example configuration
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── LICENSE
└── README.md

📦 Installing via Portainer

Method 1: Using Git Repository (Recommended)

Go to your Portainer instance
Navigate to Stacks → Add Stack
Name it: postflow-bot
Select Repository as build method
Enter repository URL: https://github.com/artcc/postflow-telegram-bot
Compose path: docker-compose.yml

Add environment variables:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_USER_ID=your_user_id
TZ=Europe/Madrid
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
OPENAI_API_KEY=your_openai_key
DATABASE_PATH=/data/postflow.db

Click Deploy the stack

Method 2: Manual Compose File

Go to your Portainer instance
Navigate to Stacks → Add Stack
Name it: postflow-bot
Select Web editor
Paste the docker-compose.yml content
Add the environment variables as shown above
Click Deploy the stack

Tip: In Portainer, you can easily edit environment variables after deployment without recreating the stack.

🔄 Updating

With Docker Compose

# Pull the latest image
docker-compose pull

# Recreate and start the container
docker-compose up -d

# Verify the update
docker logs -f postflow-bot

Note: Your data is safe! The ./data volume persists your database across updates.

With Portainer

Go to Stacks → Select postflow-bot
Click Pull and redeploy button
Wait for the update to complete
Check Containers to verify it's running

Verify Current Version

# Check image version
docker images | grep postflow-telegram-bot

# Check when the image was pulled
docker inspect ghcr.io/artcc/postflow-telegram-bot:latest | grep Created

Auto-Updates

Every push to the main branch automatically:

Builds a new Docker image
Publishes it to GitHub Container Registry
Tags it as latest

The bot uses the pre-built image from ghcr.io/artcc/postflow-telegram-bot:latest, so you just need to pull the latest version.

Note: The GitHub Container Registry package is public, so anyone can pull the image without authentication.

🛡️ Security Notes

Never commit your .env file - it contains sensitive tokens
Your bot token gives full control of your bot - keep it secret
Only the configured TELEGRAM_USER_ID can use the bot
All unauthorized access attempts are logged
API keys are stored securely in environment variables
Database is stored in a persistent Docker volume

❓ FAQ

Can I use this bot for multiple X accounts?

Currently, the bot is designed for single-user, single-account use. Each instance manages one X account. To manage multiple accounts, deploy separate instances with different configurations.

Does the bot store my API keys securely?

Yes. All API keys are stored in environment variables (.env file) which is never committed to git. The keys are only used by your self-hosted instance.

What happens if the bot crashes while scheduling posts?

Scheduled posts are stored in the SQLite database. When the bot restarts, APScheduler automatically reschedules all pending posts.

Can I use this bot without OpenAI?

Yes. OpenAI is optional. If you don't configure OPENAI_API_KEY, the bot will work perfectly fine for manual post creation and scheduling. You just won't have AI generation features or topic presets.

How do topic presets work?

Topic presets are saved keywords that trigger AI to generate posts on specific subjects. You can save up to 10 topics (e.g., "Python", "AI News", "Tech Tips"). When creating an AI post, select a topic button and the AI generates unique content about that subject each time. Topics require OpenAI to be configured.

What X API plan do I need?

You need at least Basic access tier from X's Developer Portal to post. The Free tier has very limited posting capabilities.

🐛 Troubleshooting

Bot doesn't respond

Check if container is running: docker ps
Check logs: docker logs -f postflow-bot
Verify bot token is correct in .env
Ensure bot is not rate-limited by Telegram

"Unauthorized" message

Verify your User ID is correct in .env
Use /chatid command to see your actual ID
Restart container after changing .env:
```
docker-compose restart
```

X API errors

Error: 401 Unauthorized

Check your API credentials in .env
Verify tokens haven't expired
Regenerate tokens if needed at developer.twitter.com

Error: 429 Rate Limit

X API has rate limits
Wait for rate limit reset (shown in error message)
Posts are saved and can be retried

OpenAI API errors

Invalid API Key

Verify OPENAI_API_KEY in .env
Check key hasn't expired
Ensure you have credits in your OpenAI account

Rate Limit Exceeded

OpenAI has usage limits based on your plan
Wait a few minutes before retrying
Upgrade your OpenAI plan if needed

Database issues

Database locked

Stop the container: docker-compose down
Start again: docker-compose up -d

Lost data after restart

Verify volume is mounted correctly in docker-compose.yml
Check that ./data directory exists

Permission denied errors

sudo chown -R 1000:1000 ./data
sudo chmod -R 755 ./data

🔮 Roadmap

Phase 1: MVP ✅

Phase 2: New Features

Draft system
Weekly planning wizard (rolling 7-day window)
Support for images in posts
Topic presets for AI random post generation
Additional locales (i18n)
Publication calendar with weekly view
Post templates

Phase 3: Future Features

Multi-platform support (Instagram, LinkedIn, Facebook, etc.)

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md for setup, conventions, and i18n guidelines.

🎨 Bot Avatar

You can use the official bot avatar for your own instance:

To set this image as your bot's profile picture:

Right-click the image above and save it
Open @BotFather on Telegram
Send /setuserpic
Select your bot
Upload the downloaded image

🙏 Acknowledgments

python-telegram-bot - Excellent Telegram Bot API wrapper
Tweepy - X API library
OpenAI - AI content generation
APScheduler - Advanced Python Scheduler

📧 Support

If you encounter any issues or have questions:

Check the Troubleshooting section
Search existing GitHub Issues
Open a new issue with detailed information

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

_{100% built with GitHub Copilot (GPT-5.2-Codex)}
_{Arturo Carretero Calvo — 2026}

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github		.github
assets		assets
bot		bot
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation