IP Bot

A simple async Telegram bot that responds to the /ip command with the public IP address of the server where the bot is running.

The bot fetches the address using multiple external IP detection services in parallel for reliability, works behind NAT, and restricts access to a single authorized Telegram user defined in the configuration file.

Features

• Async Telegram bot using python-telegram-bot
• Resilient parallel fetching from multiple IP providers (ipify.org, ident.me, ifconfig.me, ipinfo.io)
• Consensus-based validation - shows IP only when all providers agree
• Detailed status view - shows each provider's result with color-coded indicators
• Authorization based on Telegram user ID
• Dockerized deployment
• Configuration via environment variables

Quick Start

1. Get Your Telegram Credentials

Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the prompts to choose a name and username for your bot
4. BotFather will give you a token like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
5. Save this token - you'll need it for configuration

Get Your Telegram User ID

1. Open Telegram and search for @userinfobot
2. Send /start command
3. The bot will reply with your user ID (a number like 123456789)
4. Save this ID - only this user will be able to use your IP bot

2. Run the Bot with Docker

Option 1: Use Pre-built Image from GitHub Container Registry

Pull the latest image:

# Pull the image
docker pull ghcr.io/elisey/ipbot:latest

Create a .env file with your credentials:

TELEGRAM_TOKEN=your_bot_token_here
TELEGRAM_OWNER_ID=123456789

Create a docker-compose.yml file:

services:
  ip-bot:
    image: ghcr.io/elisey/ipbot:latest
    container_name: ipbot
    env_file:
      - .env
    restart: always

Start the bot:

# Start the bot
docker compose up -d

# View logs
docker compose logs -f

# Stop the bot
docker compose down

Option 2: Build Locally

Clone the repository:

git clone https://github.com/elisey/ipbot.git
cd ipbot

Create a .env file:

cp .env.example .env
# Edit .env and add your TELEGRAM_TOKEN and TELEGRAM_OWNER_ID

Run with docker-compose:

docker compose up -d

3. Test the Bot

Open Telegram and send /ip to your bot. It should respond with your public IP address.

Configuration

The bot is configured via environment variables in the .env file:

• TELEGRAM_TOKEN (required): Your bot token from @BotFather
• TELEGRAM_OWNER_ID (required): Your Telegram user ID - only this user can use the bot
• FETCHER_STRATEGY_ORDER (optional): IP fetchers to use, default: all

Available IP Fetchers

The bot supports multiple IP detection providers:

• ipify - ipify.org JSON API
• identme - ident.me plain text API
• ifconfig - ifconfig.me plain text API
• ipinfo - ipinfo.io plain text API
• custom - custom plain text API

Example configurations:

# Use all fetchers (default - most reliable)
FETCHER_STRATEGY_ORDER=all

# Use specific fetchers only
FETCHER_STRATEGY_ORDER=ipify,identme,ifconfig

# Use only two fetchers
FETCHER_STRATEGY_ORDER=ipify,identme

# Use single fetcher (less reliable)
FETCHER_STRATEGY_ORDER=ipify

The all keyword: When you set FETCHER_STRATEGY_ORDER=all, the bot automatically uses all available IP providers. This is the recommended configuration as it provides maximum reliability. If you add new custom fetchers to your deployment, they will automatically be included when using all.

How the Bot Works

The bot fetches your IP from all configured providers in parallel:

1. All providers agree → Shows your IP with green checkmarks ✅
2. Some providers fail → Shows IP if remaining providers agree, marks failures with ❌
3. Providers return different IPs → Shows "unknown" and displays all results with ⚠️

Troubleshooting

Bot doesn't respond to commands

Check your user ID:

• Verify TELEGRAM_OWNER_ID in .env matches your actual Telegram user ID
• Get your ID from @userinfobot to confirm

Check bot token:

• Verify TELEGRAM_TOKEN is correct (no extra spaces)
• Test the token by visiting: https://api.telegram.org/bot<YOUR_TOKEN>/getMe

"Unauthorized" message

Your Telegram user ID doesn't match TELEGRAM_OWNER_ID in the configuration. Only the specified owner can use the bot.

Check logs

# View bot logs
docker compose logs -f ip-bot

# View last 100 lines
docker compose logs --tail 100 ip-bot

Documentation

• Contributing Guide - Development setup, testing, and architecture
• Deployment Guide - Production deployment with Docker and systemd

License

MIT