# SDKWA WhatsApp Chatbot - Python SDK
[](https://badge.fury.io/py/sdkwa-whatsapp-chatbot)
[](https://pypi.org/project/sdkwa-whatsapp-chatbot/)
[](https://github.com/sdkwa/whatsapp-chatbot-python/actions/workflows/ci.yml)
[](https://github.com/sdkwa/whatsapp-chatbot-python/actions/workflows/publish.yml)
[](https://opensource.org/licenses/MIT)
A Python chatbot library that provides a **Telegraf-like interface** for building WhatsApp and Telegram bots using the SDKWA Messenger API. This library is inspired by the popular Telegraf framework for Telegram bots, bringing the same elegant API design to both WhatsApp and Telegram.
## Features
🚀 **Telegraf-Like API** - Familiar and intuitive interface for Telegram developers
📱 **Multi-Messenger Support** - Works with both WhatsApp and Telegram using the same codebase
🤖 **Easy Bot Creation** - Simple `WhatsAppBot` class with clean configuration
🎭 **Scenes & Wizards** - Create complex conversation flows and step-by-step interactions
💾 **Session Management** - Built-in session storage with memory and file backends
🔧 **Middleware Support** - Compose functionality with middleware pattern
� **Media Handling** - Send and receive photos, documents, audio, video, locations, and contacts
⌨️ **Command Handling** - Handle `/start`, `/help`, and custom commands
🎯 **Event Filtering** - Listen for specific message types and patterns
🌐 **Webhook Support** - Built-in webhook support for Flask and FastAPI
🔒 **Type Safe** - Full type hints for better development experience
## Installation
```bash
pip install sdkwa-whatsapp-chatbot
```
## Quick Start
### 1. Basic Bot
```python
import os
from sdkwa_whatsapp_chatbot import WhatsAppBot
# Create bot
bot = WhatsAppBot({
'idInstance': os.getenv('ID_INSTANCE'),
'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')
})
# Handle text messages
@bot.on('text')
async def handle_text(ctx):
await ctx.reply(f"You said: {ctx.message.text}")
# Handle commands
@bot.start()
async def start_command(ctx):
await ctx.reply('Welcome to my WhatsApp bot!')
@bot.command('hello')
async def hello_command(ctx):
await ctx.reply('Hello there! 👋')
# Launch bot
bot.launch()
```
### 2. Bot with Sessions
```python
from sdkwa_whatsapp_chatbot import WhatsAppBot, session
bot = WhatsAppBot({
'idInstance': os.getenv('ID_INSTANCE'),
'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')
})
# Enable sessions
bot.use(session())
@bot.command('count')
async def count_command(ctx):
# Access session data
count = ctx.session.get('count', 0) + 1
ctx.session['count'] = count
await ctx.reply(f"You've used this command {count} times!")
bot.launch()
```
### 3. Bot with Scenes (Conversation Flows)
```python
from sdkwa_whatsapp_chatbot import WhatsAppBot, session, BaseScene, Stage
bot = WhatsAppBot({
'idInstance': os.getenv('ID_INSTANCE'),
'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')
})
# Create a greeting scene
greeting_scene = BaseScene('greeting')
@greeting_scene.enter()
async def enter_greeting(ctx):
await ctx.reply("What's your name?")
@greeting_scene.on('text')
async def handle_name(ctx):
name = ctx.message.text
ctx.session['name'] = name
await ctx.reply(f"Nice to meet you, {name}!")
await ctx.scene.leave_scene(ctx)
# Create stage and register scene
stage = Stage([greeting_scene])
# Use middleware
bot.use(session())
bot.use(stage.middleware())
# Command to enter scene
@bot.command('greet')
async def start_greeting(ctx):
await ctx.scene_manager.enter('greeting', ctx)
bot.launch()
```
### 4. Wizard Scene (Step-by-Step)
```python
from sdkwa_whatsapp_chatbot import WhatsAppBot, session, Stage
from sdkwa_whatsapp_chatbot.scenes import WizardScene
bot = WhatsAppBot({
'idInstance': os.getenv('ID_INSTANCE'),
'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')
})
# Create registration wizard
wizard = WizardScene('registration')
@wizard.step
async def ask_name(ctx):
await ctx.reply("Step 1: What's your name?")
@wizard.step
async def ask_age(ctx):
name = ctx.message.text
await ctx.wizard.next({'name': name})
await ctx.reply("Step 2: How old are you?")
@wizard.step
async def finish(ctx):
age = ctx.message.text
await ctx.wizard.next({'age': age})
# Get all collected data
data = ctx.wizard.get_all_data()
name = data.get(0, {}).get('name')
age = data.get(1, {}).get('age')
await ctx.reply(f"Registration complete!\nName: {name}\nAge: {age}")
await ctx.wizard.complete()
# Setup
stage = Stage([wizard])
bot.use(session())
bot.use(stage.middleware())
@bot.command('register')
async def start_wizard(ctx):
await ctx.scene_manager.enter('registration', ctx)
bot.launch()
```
## API Reference
### Bot Creation
```python
from sdkwa_whatsapp_chatbot import WhatsAppBot
# Configuration options
config = {
'idInstance': 'your-instance-id',
'apiTokenInstance': 'your-api-token',
'apiUrl': 'https://api.sdkwa.pro' # Optional
}
bot = WhatsAppBot(config)
```
### Event Handlers
```python
# Listen for specific update types
@bot.on('message') # All messages
@bot.on('text') # Text messages only
@bot.on(['text', 'photo']) # Multiple types
# Listen for text patterns
@bot.hears('hello') # Exact match
@bot.hears(r'hello.*') # Regex pattern
# Listen for commands
@bot.command('start') # /start command
@bot.start() # Alias for /start
@bot.help() # Alias for /help
```
### Context Methods
```python
async def handler(ctx):
# Send messages
await ctx.reply('Hello!')
await ctx.reply_with_photo('https://example.com/photo.jpg', caption='Photo')
await ctx.reply_with_document('https://example.com/doc.pdf')
await ctx.reply_with_location(40.7128, -74.0060, 'New York')
await ctx.reply_with_contact('+1234567890', 'John', 'Doe')
# Message info
text = ctx.message.text
chat_id = ctx.chat_id
sender = ctx.from_user
# Command helpers
command = ctx.get_command() # Get command name
args = ctx.get_command_args() # Get command arguments
# Session access
ctx.session['key'] = 'value'
value = ctx.session.get('key')
```
### Session Management
```python
from sdkwa_whatsapp_chatbot import session, MemorySessionStore, FileSessionStore
# Use memory store (default)
bot.use(session())
# Use file store
bot.use(session(store=FileSessionStore('sessions.json')))
# Custom session key
def custom_key(ctx):
return f"{ctx.chat_id}:{ctx.from_user.get('id', 'anonymous')}"
bot.use(session(key_generator=custom_key))
```
### Scene Management
```python
from sdkwa_whatsapp_chatbot import BaseScene, Stage
# Create scene
scene = BaseScene('my_scene')
@scene.enter()
async def on_enter(ctx):
await ctx.reply("Entered scene!")
@scene.leave()
async def on_leave(ctx):
await ctx.reply("Left scene!")
@scene.on('text')
async def handle_text(ctx):
await ctx.reply("In scene: " + ctx.message.text)
# Scene state management
@scene.on('text')
async def save_data(ctx):
scene.update_state(ctx, {'user_input': ctx.message.text})
state = scene.get_state(ctx)
# Create stage
stage = Stage([scene])
bot.use(stage.middleware())
# Scene navigation
@bot.command('enter')
async def enter_scene(ctx):
await ctx.scene_manager.enter('my_scene', ctx)
```
### Wizard Scenes
```python
from sdkwa_whatsapp_chatbot.scenes import WizardScene
wizard = WizardScene('my_wizard')
@wizard.step
async def step1(ctx):
await ctx.reply("Step 1: Enter your name")
@wizard.step
async def step2(ctx):
name = ctx.message.text
await ctx.wizard.next({'name': name})
await ctx.reply("Step 2: Enter your age")
@wizard.step
async def step3(ctx):
age = ctx.message.text
await ctx.wizard.next({'age': age})
# Get all data
all_data = ctx.wizard.get_all_data()
await ctx.reply(f"Done! Name: {all_data[0]['name']}, Age: {all_data[1]['age']}")
await ctx.wizard.complete()
# Wizard navigation
async def handler(ctx):
await ctx.wizard.next() # Next step
await ctx.wizard.previous() # Previous step
await ctx.wizard.jump_to(2) # Jump to step
progress = ctx.wizard.progress # Get progress info
```
### Media Handling
```python
# Send media
await ctx.reply_with_photo(
photo_url='https://example.com/photo.jpg',
caption='A nice photo'
)
await ctx.reply_with_document(
document_url='https://example.com/doc.pdf',
caption='Important document'
)
# Handle received media
@bot.on('message')
async def handle_media(ctx):
if ctx.message.message_type == 'imageMessage':
await ctx.reply("Received a photo!")
# Download URL: ctx.message.file_url
elif ctx.message.message_type == 'documentMessage':
await ctx.reply(f"Received document: {ctx.message.file_name}")
```
### Webhook Support
```python
# Flask webhook
from flask import Flask
app = Flask(__name__)
bot.flask_webhook(app, '/webhook')
# FastAPI webhook
from fastapi import FastAPI
app = FastAPI()
bot.fastapi_webhook(app, '/webhook')
# Custom webhook
callback = bot.webhook_callback()
# Use callback in your web framework
```
### Error Handling
```python
@bot.catch
async def error_handler(error, ctx):
print(f"Error: {error}")
if ctx:
await ctx.reply("Sorry, something went wrong!")
```
## Telegram Support
Starting from version 1.0.4 of the underlying `sdkwa-whatsapp-api-client`, the library now supports **both WhatsApp and Telegram** using the same API!
### Using Telegram
Simply specify `messenger_type="telegram"` when creating your bot:
```python
from sdkwa_whatsapp_chatbot import WhatsAppBot
# Create a Telegram bot
bot = WhatsAppBot(
config={
'idInstance': 'your-instance-id',
'apiTokenInstance': 'your-api-token'
},
messenger_type="telegram" # Use Telegram instead of WhatsApp
)
# The rest of your code remains identical!
@bot.command('start')
async def start_command(ctx):
await ctx.reply('Hello from Telegram! 👋')
bot.launch()
```
### Multi-Messenger Bot
You can even build a bot that works with both messengers:
```python
import os
from sdkwa_whatsapp_chatbot import WhatsAppBot
# Get messenger type from environment
messenger = os.getenv('MESSENGER_TYPE', 'whatsapp') # 'whatsapp' or 'telegram'
bot = WhatsAppBot(config, messenger_type=messenger)
@bot.command('start')
async def start_command(ctx):
# Access the current messenger type
await ctx.reply(f'Hello from {ctx.messenger_type.capitalize()}! 👋')
bot.launch()
```
### Telegram-Specific Notes
1. **Chat IDs**: Telegram uses numeric chat IDs (e.g., `"1234567890"`) instead of WhatsApp's format (`"1234567890@c.us"`)
2. **Authorization**: Telegram uses confirmation codes instead of QR codes
3. **API Compatibility**: All bot methods (send_message, send_photo, etc.) work identically for both messengers
### Authorization for Telegram
Before using Telegram, you need to authorize with a confirmation code:
```python
from sdkwa import SDKWA
client = SDKWA(
id_instance="your-instance-id",
api_token_instance="your-api-token",
messenger="telegram"
)
# Step 1: Send confirmation code to your phone
client.send_confirmation_code(phone_number=1234567890, messenger="telegram")
# Step 2: Enter the code you received
client.sign_in_with_confirmation_code(code="YOUR_CODE", messenger="telegram")
# Now you can use the bot!
```
## Examples
The `examples/` directory contains several complete examples:
### WhatsApp Examples
- [`hello_bot.py`](examples/hello_bot.py) - Simple hello bot
- [`echo_bot.py`](examples/echo_bot.py) - Echo messages and files
- [`scene_bot.py`](examples/scene_bot.py) - Conversation scenes
- [`wizard_bot.py`](examples/wizard_bot.py) - Step-by-step wizards
- [`media_bot.py`](examples/media_bot.py) - Media file handling
### Telegram Examples
- [`telegram_bot.py`](examples/telegram_bot.py) - Telegram bot example
- [`multi_messenger_bot.py`](examples/multi_messenger_bot.py) - Bot that works with both WhatsApp and Telegram
## Configuration
### Environment Variables
```bash
export ID_INSTANCE="your_instance_id"
export API_TOKEN_INSTANCE="your_api_token"
```
### Configuration Object
```python
config = {
'idInstance': 'your-instance-id',
'apiTokenInstance': 'your-api-token',
'apiUrl': 'https://api.sdkwa.pro', # Optional
# Bot options
'polling_interval': 1, # Seconds between polls
'max_retries': 3, # Max retry attempts
'retry_delay': 5 # Delay between retries
}
bot = WhatsAppBot(config)
```
## Getting SDKWA Credentials
1. Sign up at [SDKWA](https://sdkwa.pro)
2. Create a new WhatsApp instance
3. Get your `idInstance` and `apiTokenInstance` from the dashboard
4. Use these credentials in your bot configuration
## Comparison with JavaScript Version
This Python library provides the same functionality as the JavaScript `@sdkwa/whatsapp-chatbot` package:
| Feature | JavaScript | Python | Status |
|---------|------------|--------|--------|
| Basic Bot | ✅ | ✅ | Complete |
| Commands | ✅ | ✅ | Complete |
| Scenes | ✅ | ✅ | Complete |
| Sessions | ✅ | ✅ | Complete |
| Middleware | ✅ | ✅ | Complete |
| Media Files | ✅ | ✅ | Complete |
| Webhooks | ✅ | ✅ | Complete |
| Error Handling | ✅ | ✅ | Complete |
## Requirements
- Python 3.8+
- `sdkwa-whatsapp-api-client` >= 1.0.0
- `typing-extensions` >= 4.0.0
- `pydantic` >= 2.0.0
## Development
### Setting up development environment
```bash
# Clone the repository
git clone https://github.com/sdkwa/whatsapp-chatbot-python.git
cd whatsapp-chatbot-python
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest
# Format code
black sdkwa_whatsapp_chatbot/
isort sdkwa_whatsapp_chatbot/
# Type checking
mypy sdkwa_whatsapp_chatbot/
```
## Development Setup
### Using Make (Recommended)
```bash
# Install development dependencies
make install-dev
# Run tests
make test
# Format code
make format
# Check formatting
make format-check
# Run linting
make lint
# Build package
make build
# Clean build artifacts
make clean
```
### Manual Setup
```bash
# Clone repository
git clone https://github.com/sdkwa/whatsapp-chatbot-python.git
cd whatsapp-chatbot-python
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Set up pre-commit hooks (optional but recommended)
pip install pre-commit
pre-commit install
# Run tests
pytest
# Format code
black .
isort .
# Type checking
mypy sdkwa_whatsapp_chatbot
```
### Publishing
For maintainers, see [PUBLISHING.md](PUBLISHING.md) for detailed instructions on publishing to PyPI.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📚 [Documentation](https://docs.sdkwa.pro)
- 💬 [Telegram Support](https://t.me/sdkwa_support)
- 🌐 [Official Website](https://sdkwa.pro)
- 🐛 [Report Issues](https://github.com/sdkwa/whatsapp-chatbot-python/issues)
## Changelog
### v1.0.0
- Initial release
- Telegraf-like API for WhatsApp bots
- Scene and wizard support
- Session management
- Media handling
- Webhook support
- Complete examples and documentation
Raw data
{
"_id": null,
"home_page": "https://github.com/sdkwa/whatsapp-chatbot-python",
"name": "sdkwa-whatsapp-chatbot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "SDKWA Community <support@sdkwa.pro>",
"keywords": "whatsapp, chatbot, sdkwa, telegraf, messaging, api, bot, automation",
"author": "SDKWA Community",
"author_email": "SDKWA Community <support@sdkwa.pro>",
"download_url": "https://files.pythonhosted.org/packages/24/c8/51611049f215cdd2121f6a00f208af64e2337b2e506718e08d56ca99781d/sdkwa_whatsapp_chatbot-1.0.4.tar.gz",
"platform": null,
"description": "# SDKWA WhatsApp Chatbot - Python SDK\n\n[](https://badge.fury.io/py/sdkwa-whatsapp-chatbot)\n[](https://pypi.org/project/sdkwa-whatsapp-chatbot/)\n[](https://github.com/sdkwa/whatsapp-chatbot-python/actions/workflows/ci.yml)\n[](https://github.com/sdkwa/whatsapp-chatbot-python/actions/workflows/publish.yml)\n[](https://opensource.org/licenses/MIT)\n\nA Python chatbot library that provides a **Telegraf-like interface** for building WhatsApp and Telegram bots using the SDKWA Messenger API. This library is inspired by the popular Telegraf framework for Telegram bots, bringing the same elegant API design to both WhatsApp and Telegram.\n\n## Features\n\n\ud83d\ude80 **Telegraf-Like API** - Familiar and intuitive interface for Telegram developers \n\ud83d\udcf1 **Multi-Messenger Support** - Works with both WhatsApp and Telegram using the same codebase \n\ud83e\udd16 **Easy Bot Creation** - Simple `WhatsAppBot` class with clean configuration \n\ud83c\udfad **Scenes & Wizards** - Create complex conversation flows and step-by-step interactions \n\ud83d\udcbe **Session Management** - Built-in session storage with memory and file backends \n\ud83d\udd27 **Middleware Support** - Compose functionality with middleware pattern \n\ufffd **Media Handling** - Send and receive photos, documents, audio, video, locations, and contacts \n\u2328\ufe0f **Command Handling** - Handle `/start`, `/help`, and custom commands \n\ud83c\udfaf **Event Filtering** - Listen for specific message types and patterns \n\ud83c\udf10 **Webhook Support** - Built-in webhook support for Flask and FastAPI \n\ud83d\udd12 **Type Safe** - Full type hints for better development experience \n\n## Installation\n\n```bash\npip install sdkwa-whatsapp-chatbot\n```\n\n## Quick Start\n\n### 1. Basic Bot\n\n```python\nimport os\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot\n\n# Create bot\nbot = WhatsAppBot({\n 'idInstance': os.getenv('ID_INSTANCE'),\n 'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')\n})\n\n# Handle text messages\n@bot.on('text')\nasync def handle_text(ctx):\n await ctx.reply(f\"You said: {ctx.message.text}\")\n\n# Handle commands\n@bot.start()\nasync def start_command(ctx):\n await ctx.reply('Welcome to my WhatsApp bot!')\n\n@bot.command('hello')\nasync def hello_command(ctx):\n await ctx.reply('Hello there! \ud83d\udc4b')\n\n# Launch bot\nbot.launch()\n```\n\n### 2. Bot with Sessions\n\n```python\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot, session\n\nbot = WhatsAppBot({\n 'idInstance': os.getenv('ID_INSTANCE'),\n 'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')\n})\n\n# Enable sessions\nbot.use(session())\n\n@bot.command('count')\nasync def count_command(ctx):\n # Access session data\n count = ctx.session.get('count', 0) + 1\n ctx.session['count'] = count\n await ctx.reply(f\"You've used this command {count} times!\")\n\nbot.launch()\n```\n\n### 3. Bot with Scenes (Conversation Flows)\n\n```python\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot, session, BaseScene, Stage\n\nbot = WhatsAppBot({\n 'idInstance': os.getenv('ID_INSTANCE'),\n 'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')\n})\n\n# Create a greeting scene\ngreeting_scene = BaseScene('greeting')\n\n@greeting_scene.enter()\nasync def enter_greeting(ctx):\n await ctx.reply(\"What's your name?\")\n\n@greeting_scene.on('text')\nasync def handle_name(ctx):\n name = ctx.message.text\n ctx.session['name'] = name\n await ctx.reply(f\"Nice to meet you, {name}!\")\n await ctx.scene.leave_scene(ctx)\n\n# Create stage and register scene\nstage = Stage([greeting_scene])\n\n# Use middleware\nbot.use(session())\nbot.use(stage.middleware())\n\n# Command to enter scene\n@bot.command('greet')\nasync def start_greeting(ctx):\n await ctx.scene_manager.enter('greeting', ctx)\n\nbot.launch()\n```\n\n### 4. Wizard Scene (Step-by-Step)\n\n```python\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot, session, Stage\nfrom sdkwa_whatsapp_chatbot.scenes import WizardScene\n\nbot = WhatsAppBot({\n 'idInstance': os.getenv('ID_INSTANCE'),\n 'apiTokenInstance': os.getenv('API_TOKEN_INSTANCE')\n})\n\n# Create registration wizard\nwizard = WizardScene('registration')\n\n@wizard.step\nasync def ask_name(ctx):\n await ctx.reply(\"Step 1: What's your name?\")\n\n@wizard.step\nasync def ask_age(ctx):\n name = ctx.message.text\n await ctx.wizard.next({'name': name})\n await ctx.reply(\"Step 2: How old are you?\")\n\n@wizard.step\nasync def finish(ctx):\n age = ctx.message.text\n await ctx.wizard.next({'age': age})\n \n # Get all collected data\n data = ctx.wizard.get_all_data()\n name = data.get(0, {}).get('name')\n age = data.get(1, {}).get('age')\n \n await ctx.reply(f\"Registration complete!\\nName: {name}\\nAge: {age}\")\n await ctx.wizard.complete()\n\n# Setup\nstage = Stage([wizard])\nbot.use(session())\nbot.use(stage.middleware())\n\n@bot.command('register')\nasync def start_wizard(ctx):\n await ctx.scene_manager.enter('registration', ctx)\n\nbot.launch()\n```\n\n## API Reference\n\n### Bot Creation\n\n```python\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot\n\n# Configuration options\nconfig = {\n 'idInstance': 'your-instance-id',\n 'apiTokenInstance': 'your-api-token',\n 'apiUrl': 'https://api.sdkwa.pro' # Optional\n}\n\nbot = WhatsAppBot(config)\n```\n\n### Event Handlers\n\n```python\n# Listen for specific update types\n@bot.on('message') # All messages\n@bot.on('text') # Text messages only\n@bot.on(['text', 'photo']) # Multiple types\n\n# Listen for text patterns\n@bot.hears('hello') # Exact match\n@bot.hears(r'hello.*') # Regex pattern\n\n# Listen for commands\n@bot.command('start') # /start command\n@bot.start() # Alias for /start\n@bot.help() # Alias for /help\n```\n\n### Context Methods\n\n```python\nasync def handler(ctx):\n # Send messages\n await ctx.reply('Hello!')\n await ctx.reply_with_photo('https://example.com/photo.jpg', caption='Photo')\n await ctx.reply_with_document('https://example.com/doc.pdf')\n await ctx.reply_with_location(40.7128, -74.0060, 'New York')\n await ctx.reply_with_contact('+1234567890', 'John', 'Doe')\n \n # Message info\n text = ctx.message.text\n chat_id = ctx.chat_id\n sender = ctx.from_user\n \n # Command helpers\n command = ctx.get_command() # Get command name\n args = ctx.get_command_args() # Get command arguments\n \n # Session access\n ctx.session['key'] = 'value'\n value = ctx.session.get('key')\n```\n\n### Session Management\n\n```python\nfrom sdkwa_whatsapp_chatbot import session, MemorySessionStore, FileSessionStore\n\n# Use memory store (default)\nbot.use(session())\n\n# Use file store\nbot.use(session(store=FileSessionStore('sessions.json')))\n\n# Custom session key\ndef custom_key(ctx):\n return f\"{ctx.chat_id}:{ctx.from_user.get('id', 'anonymous')}\"\n\nbot.use(session(key_generator=custom_key))\n```\n\n### Scene Management\n\n```python\nfrom sdkwa_whatsapp_chatbot import BaseScene, Stage\n\n# Create scene\nscene = BaseScene('my_scene')\n\n@scene.enter()\nasync def on_enter(ctx):\n await ctx.reply(\"Entered scene!\")\n\n@scene.leave()\nasync def on_leave(ctx):\n await ctx.reply(\"Left scene!\")\n\n@scene.on('text')\nasync def handle_text(ctx):\n await ctx.reply(\"In scene: \" + ctx.message.text)\n\n# Scene state management\n@scene.on('text')\nasync def save_data(ctx):\n scene.update_state(ctx, {'user_input': ctx.message.text})\n state = scene.get_state(ctx)\n\n# Create stage\nstage = Stage([scene])\nbot.use(stage.middleware())\n\n# Scene navigation\n@bot.command('enter')\nasync def enter_scene(ctx):\n await ctx.scene_manager.enter('my_scene', ctx)\n```\n\n### Wizard Scenes\n\n```python\nfrom sdkwa_whatsapp_chatbot.scenes import WizardScene\n\nwizard = WizardScene('my_wizard')\n\n@wizard.step\nasync def step1(ctx):\n await ctx.reply(\"Step 1: Enter your name\")\n\n@wizard.step\nasync def step2(ctx):\n name = ctx.message.text\n await ctx.wizard.next({'name': name})\n await ctx.reply(\"Step 2: Enter your age\")\n\n@wizard.step\nasync def step3(ctx):\n age = ctx.message.text\n await ctx.wizard.next({'age': age})\n \n # Get all data\n all_data = ctx.wizard.get_all_data()\n await ctx.reply(f\"Done! Name: {all_data[0]['name']}, Age: {all_data[1]['age']}\")\n await ctx.wizard.complete()\n\n# Wizard navigation\nasync def handler(ctx):\n await ctx.wizard.next() # Next step\n await ctx.wizard.previous() # Previous step\n await ctx.wizard.jump_to(2) # Jump to step\n progress = ctx.wizard.progress # Get progress info\n```\n\n### Media Handling\n\n```python\n# Send media\nawait ctx.reply_with_photo(\n photo_url='https://example.com/photo.jpg',\n caption='A nice photo'\n)\n\nawait ctx.reply_with_document(\n document_url='https://example.com/doc.pdf',\n caption='Important document'\n)\n\n# Handle received media\n@bot.on('message')\nasync def handle_media(ctx):\n if ctx.message.message_type == 'imageMessage':\n await ctx.reply(\"Received a photo!\")\n # Download URL: ctx.message.file_url\n \n elif ctx.message.message_type == 'documentMessage':\n await ctx.reply(f\"Received document: {ctx.message.file_name}\")\n```\n\n### Webhook Support\n\n```python\n# Flask webhook\nfrom flask import Flask\napp = Flask(__name__)\nbot.flask_webhook(app, '/webhook')\n\n# FastAPI webhook\nfrom fastapi import FastAPI\napp = FastAPI()\nbot.fastapi_webhook(app, '/webhook')\n\n# Custom webhook\ncallback = bot.webhook_callback()\n# Use callback in your web framework\n```\n\n### Error Handling\n\n```python\n@bot.catch\nasync def error_handler(error, ctx):\n print(f\"Error: {error}\")\n if ctx:\n await ctx.reply(\"Sorry, something went wrong!\")\n```\n\n## Telegram Support\n\nStarting from version 1.0.4 of the underlying `sdkwa-whatsapp-api-client`, the library now supports **both WhatsApp and Telegram** using the same API!\n\n### Using Telegram\n\nSimply specify `messenger_type=\"telegram\"` when creating your bot:\n\n```python\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot\n\n# Create a Telegram bot\nbot = WhatsAppBot(\n config={\n 'idInstance': 'your-instance-id',\n 'apiTokenInstance': 'your-api-token'\n },\n messenger_type=\"telegram\" # Use Telegram instead of WhatsApp\n)\n\n# The rest of your code remains identical!\n@bot.command('start')\nasync def start_command(ctx):\n await ctx.reply('Hello from Telegram! \ud83d\udc4b')\n\nbot.launch()\n```\n\n### Multi-Messenger Bot\n\nYou can even build a bot that works with both messengers:\n\n```python\nimport os\nfrom sdkwa_whatsapp_chatbot import WhatsAppBot\n\n# Get messenger type from environment\nmessenger = os.getenv('MESSENGER_TYPE', 'whatsapp') # 'whatsapp' or 'telegram'\n\nbot = WhatsAppBot(config, messenger_type=messenger)\n\n@bot.command('start')\nasync def start_command(ctx):\n # Access the current messenger type\n await ctx.reply(f'Hello from {ctx.messenger_type.capitalize()}! \ud83d\udc4b')\n\nbot.launch()\n```\n\n### Telegram-Specific Notes\n\n1. **Chat IDs**: Telegram uses numeric chat IDs (e.g., `\"1234567890\"`) instead of WhatsApp's format (`\"1234567890@c.us\"`)\n2. **Authorization**: Telegram uses confirmation codes instead of QR codes\n3. **API Compatibility**: All bot methods (send_message, send_photo, etc.) work identically for both messengers\n\n### Authorization for Telegram\n\nBefore using Telegram, you need to authorize with a confirmation code:\n\n```python\nfrom sdkwa import SDKWA\n\nclient = SDKWA(\n id_instance=\"your-instance-id\",\n api_token_instance=\"your-api-token\",\n messenger=\"telegram\"\n)\n\n# Step 1: Send confirmation code to your phone\nclient.send_confirmation_code(phone_number=1234567890, messenger=\"telegram\")\n\n# Step 2: Enter the code you received\nclient.sign_in_with_confirmation_code(code=\"YOUR_CODE\", messenger=\"telegram\")\n\n# Now you can use the bot!\n```\n\n## Examples\n\nThe `examples/` directory contains several complete examples:\n\n### WhatsApp Examples\n- [`hello_bot.py`](examples/hello_bot.py) - Simple hello bot\n- [`echo_bot.py`](examples/echo_bot.py) - Echo messages and files\n- [`scene_bot.py`](examples/scene_bot.py) - Conversation scenes\n- [`wizard_bot.py`](examples/wizard_bot.py) - Step-by-step wizards\n- [`media_bot.py`](examples/media_bot.py) - Media file handling\n\n### Telegram Examples\n- [`telegram_bot.py`](examples/telegram_bot.py) - Telegram bot example\n- [`multi_messenger_bot.py`](examples/multi_messenger_bot.py) - Bot that works with both WhatsApp and Telegram\n\n## Configuration\n\n### Environment Variables\n\n```bash\nexport ID_INSTANCE=\"your_instance_id\"\nexport API_TOKEN_INSTANCE=\"your_api_token\"\n```\n\n### Configuration Object\n\n```python\nconfig = {\n 'idInstance': 'your-instance-id',\n 'apiTokenInstance': 'your-api-token',\n 'apiUrl': 'https://api.sdkwa.pro', # Optional\n \n # Bot options\n 'polling_interval': 1, # Seconds between polls\n 'max_retries': 3, # Max retry attempts\n 'retry_delay': 5 # Delay between retries\n}\n\nbot = WhatsAppBot(config)\n```\n\n## Getting SDKWA Credentials\n\n1. Sign up at [SDKWA](https://sdkwa.pro)\n2. Create a new WhatsApp instance\n3. Get your `idInstance` and `apiTokenInstance` from the dashboard\n4. Use these credentials in your bot configuration\n\n## Comparison with JavaScript Version\n\nThis Python library provides the same functionality as the JavaScript `@sdkwa/whatsapp-chatbot` package:\n\n| Feature | JavaScript | Python | Status |\n|---------|------------|--------|--------|\n| Basic Bot | \u2705 | \u2705 | Complete |\n| Commands | \u2705 | \u2705 | Complete |\n| Scenes | \u2705 | \u2705 | Complete |\n| Sessions | \u2705 | \u2705 | Complete |\n| Middleware | \u2705 | \u2705 | Complete |\n| Media Files | \u2705 | \u2705 | Complete |\n| Webhooks | \u2705 | \u2705 | Complete |\n| Error Handling | \u2705 | \u2705 | Complete |\n\n## Requirements\n\n- Python 3.8+\n- `sdkwa-whatsapp-api-client` >= 1.0.0\n- `typing-extensions` >= 4.0.0\n- `pydantic` >= 2.0.0\n\n## Development\n\n### Setting up development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/sdkwa/whatsapp-chatbot-python.git\ncd whatsapp-chatbot-python\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Format code\nblack sdkwa_whatsapp_chatbot/\nisort sdkwa_whatsapp_chatbot/\n\n# Type checking\nmypy sdkwa_whatsapp_chatbot/\n```\n\n## Development Setup\n\n### Using Make (Recommended)\n\n```bash\n# Install development dependencies\nmake install-dev\n\n# Run tests\nmake test\n\n# Format code\nmake format\n\n# Check formatting\nmake format-check\n\n# Run linting\nmake lint\n\n# Build package\nmake build\n\n# Clean build artifacts\nmake clean\n```\n\n### Manual Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/sdkwa/whatsapp-chatbot-python.git\ncd whatsapp-chatbot-python\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .[dev]\n\n# Set up pre-commit hooks (optional but recommended)\npip install pre-commit\npre-commit install\n\n# Run tests\npytest\n\n# Format code\nblack .\nisort .\n\n# Type checking\nmypy sdkwa_whatsapp_chatbot\n```\n\n### Publishing\n\nFor maintainers, see [PUBLISHING.md](PUBLISHING.md) for detailed instructions on publishing to PyPI.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udcda [Documentation](https://docs.sdkwa.pro)\n- \ud83d\udcac [Telegram Support](https://t.me/sdkwa_support)\n- \ud83c\udf10 [Official Website](https://sdkwa.pro)\n- \ud83d\udc1b [Report Issues](https://github.com/sdkwa/whatsapp-chatbot-python/issues)\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Telegraf-like API for WhatsApp bots\n- Scene and wizard support\n- Session management\n- Media handling\n- Webhook support\n- Complete examples and documentation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "WhatsApp Chatbot library for Python based on SDKWA API with Telegraf-like interface",
"version": "1.0.4",
"project_urls": {
"Changelog": "https://github.com/sdkwa/whatsapp-chatbot-python/blob/main/CHANGELOG.md",
"Documentation": "https://docs.sdkwa.pro",
"Homepage": "https://github.com/sdkwa/whatsapp-chatbot-python",
"Issues": "https://github.com/sdkwa/whatsapp-chatbot-python/issues",
"Repository": "https://github.com/sdkwa/whatsapp-chatbot-python"
},
"split_keywords": [
"whatsapp",
" chatbot",
" sdkwa",
" telegraf",
" messaging",
" api",
" bot",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79cf5d4e95b07dfd657866029d9a7ec5b7bf828678daa3fb7bce5e99df926ccb",
"md5": "148f817cfdc91243c8d25f0bafc6bdf4",
"sha256": "149386c071cd5481de92a5199ccc03be711661e3802bf347e10fe3ffe0690ccb"
},
"downloads": -1,
"filename": "sdkwa_whatsapp_chatbot-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "148f817cfdc91243c8d25f0bafc6bdf4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26195,
"upload_time": "2025-10-08T15:48:01",
"upload_time_iso_8601": "2025-10-08T15:48:01.512335Z",
"url": "https://files.pythonhosted.org/packages/79/cf/5d4e95b07dfd657866029d9a7ec5b7bf828678daa3fb7bce5e99df926ccb/sdkwa_whatsapp_chatbot-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "24c851611049f215cdd2121f6a00f208af64e2337b2e506718e08d56ca99781d",
"md5": "98224f5d288e285301386b41f872d7f6",
"sha256": "3a85f5246cb81157e520f01e528be9dfc75dab155c9a22583fca5110d285d15d"
},
"downloads": -1,
"filename": "sdkwa_whatsapp_chatbot-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "98224f5d288e285301386b41f872d7f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 42063,
"upload_time": "2025-10-08T15:48:03",
"upload_time_iso_8601": "2025-10-08T15:48:03.089137Z",
"url": "https://files.pythonhosted.org/packages/24/c8/51611049f215cdd2121f6a00f208af64e2337b2e506718e08d56ca99781d/sdkwa_whatsapp_chatbot-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 15:48:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdkwa",
"github_project": "whatsapp-chatbot-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sdkwa-whatsapp-api-client",
"specs": [
[
">=",
"1.0.4"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "flask",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.100.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.20.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
">=",
"5.12.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "sdkwa-whatsapp-chatbot"
}
JSON
