WordBot - Telegram Dictionary Bot 📚

A simple and efficient Telegram bot that provides English word definitions, pronunciations, and examples using the Free Dictionary API.

Features ✨

• 🔍 Word Definitions: Get comprehensive definitions for English words
• 🔤 Pronunciations: IPA phonetic transcriptions for proper pronunciation
• 📝 Examples: Real-world usage examples for better understanding
• 🎯 Part of Speech: Clear categorization (noun, verb, adjective, etc.)
• ⚡ Fast Response: Quick dictionary lookups with timeout handling
• 🛡️ Error Handling: Robust error management and user-friendly messages
• 📖 Source Attribution: Credits Wiktionary as the data source

Demo

Send any English word to the bot and get instant definitions:

User: hello
Bot: **hello**
🔤 /həˈləʊ/ • /hɛˈləʊ/ • /hɛˈloʊ/

📖 Meanings:
**interjection**: A greeting (salutation) said when meeting someone or acknowledging someone's arrival or presence.
_Example_: Hello, everyone.

**interjection**: A greeting used when answering the telephone.
_Example_: Hello? How may I help you?

_Source: Wiktionary_

Prerequisites 📋

• Python 3.7+
• A Telegram Bot Token from @BotFather
• Internet connection for API calls

Installation 🚀

1. Clone the repository

   git clone https://github.com/yourusername/wordbot-telegram.git
   cd wordbot-telegram

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment variables

   Create a .env file in the project root:

   BOT_TOKEN=your_telegram_bot_token_here

4. Run the bot

   python main.py

Requirements 📦

Create a requirements.txt file:

python-telegram-bot==20.7
requests==2.31.0
python-dotenv==1.0.0

Project Structure 📁

wordbot-telegram/
│
├── main.py                 # Main bot application
├── .env                    # Environment variables (create this)
├── requirements.txt        # Python dependencies
└── README.md              # This file

Getting a Telegram Bot Token 🤖

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts to create your bot
4. Copy the bot token and add it to your .env file

API Information 🔌

This bot uses the Free Dictionary API:

• Endpoint: https://freedictionaryapi.com/api/v1/entries/en/
• Data Source: Wiktionary
• Rate Limiting: No official limits mentioned
• License: CC BY-SA 4.0

Usage 💬

Available Commands

• /start - Welcome message and instructions
• Send any English word - Get definition, pronunciation, and examples

Supported Features

• ✅ Single English words (e.g., "hello", "computer", "amazing")
• ✅ Common words and technical terms
• ✅ Multiple definitions per word
• ✅ Pronunciation guides (IPA format)
• ✅ Usage examples
• ❌ Multi-word phrases (currently not supported)
• ❌ Non-English words

Configuration ⚙️

Environment Variables

Variable	Description	Required
BOT_TOKEN	Your Telegram bot token from BotFather	Yes

Customization Options

You can modify these settings in main.py:

# Maximum definitions per word (default: 5)
if definition_count >= 5:
    break

# API timeout (default: 10 seconds)
response = requests.get(API_URL + word, timeout=10)

# Maximum pronunciations shown (default: 3)
if len(phonetic_texts) >= 3:
    break

Error Handling 🛠️

The bot handles various error scenarios:

• Network Issues: Timeout and connection errors
• Invalid Words: Words not found in dictionary
• API Errors: Service unavailable or malformed responses
• Rate Limiting: Automatic retry logic (if implemented)
• Multi-word Input: Prompts user to send single words only

Logging 📊

The bot includes comprehensive logging:

# Log levels
INFO  - Normal operations and successful requests
WARN  - API issues and invalid responses  
ERROR - Network errors and exceptions

Logs include:

• User requests and responses
• API call results
• Error details for debugging

Deployment Options 🌐

Local Development

python main.py

Production Deployment

Using systemd (Linux):

1. Create service file /etc/systemd/system/wordbot.service:

[Unit]
Description=WordBot Telegram Bot
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/wordbot
ExecStart=/usr/bin/python3 /path/to/wordbot/main.py
Restart=always

[Install]
WantedBy=multi-user.target

2. Enable and start:

sudo systemctl enable wordbot
sudo systemctl start wordbot

Using Docker:

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "main.py"]

Contributing 🤝

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Troubleshooting 🔧

Common Issues

Bot not responding:

• Check if bot token is correct
• Verify internet connection
• Check logs for error messages

"Word not found" errors:

• API might be temporarily unavailable
• Try with common English words first
• Check API status at freedictionaryapi.com

Installation issues:

• Ensure Python 3.7+ is installed
• Try using virtual environment:

  python -m venv venv
  source venv/bin/activate  # Linux/Mac
  # or
  venv\Scripts\activate     # Windows
  pip install -r requirements.txt

Debug Mode

Enable debug logging by changing:

level=logging.DEBUG

License 📄

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

Acknowledgments 🙏

• Free Dictionary API for providing the dictionary data
• Wiktionary for the comprehensive word database
• python-telegram-bot library for Telegram integration

Support 💪

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Review the logs for error messages
3. Open an issue on GitHub with:
   • Error message/logs
   • Steps to reproduce
   • Your environment details

---

Happy word learning! 📚✨