# 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 bots using the SDKWA WhatsApp API. This library is inspired by the popular Telegraf framework for Telegram bots, bringing the same elegant API design to WhatsApp.
## Features
🚀 **Telegraf-Like API** - Familiar and intuitive interface for Telegram developers
🤖 **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!")
```
## Examples
The `examples/` directory contains several complete 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
## 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/10/98/508fffd0ec8bac7ee2705cf914e6ea433fb14f0b2106b0053a39cf85ef72/sdkwa_whatsapp_chatbot-1.0.2.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 bots using the SDKWA WhatsApp API. This library is inspired by the popular Telegraf framework for Telegram bots, bringing the same elegant API design to WhatsApp.\n\n## Features\n\n\ud83d\ude80 **Telegraf-Like API** - Familiar and intuitive interface for Telegram developers \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\ud83d\udcf1 **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## Examples\n\nThe `examples/` directory contains several complete examples:\n\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## 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.2",
"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": "bc3e385f1fb46976104be59f1d5fd6b4b73725b06ca5888ec0712d64db81e647",
"md5": "d29b42b6d242758dfd1b3e6242ee890c",
"sha256": "ee8c2778bc6204c27561a56f0a78725ff994ff024979ed4c77c67903569a79a5"
},
"downloads": -1,
"filename": "sdkwa_whatsapp_chatbot-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d29b42b6d242758dfd1b3e6242ee890c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24020,
"upload_time": "2025-07-09T10:53:46",
"upload_time_iso_8601": "2025-07-09T10:53:46.314092Z",
"url": "https://files.pythonhosted.org/packages/bc/3e/385f1fb46976104be59f1d5fd6b4b73725b06ca5888ec0712d64db81e647/sdkwa_whatsapp_chatbot-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1098508fffd0ec8bac7ee2705cf914e6ea433fb14f0b2106b0053a39cf85ef72",
"md5": "5df8ab0254107f8b4cee08a158c78064",
"sha256": "36fbbf6440f2d0eb29f11ea4df7077d47a0a8823f482303364a1fbecccbd400a"
},
"downloads": -1,
"filename": "sdkwa_whatsapp_chatbot-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5df8ab0254107f8b4cee08a158c78064",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 37742,
"upload_time": "2025-07-09T10:53:47",
"upload_time_iso_8601": "2025-07-09T10:53:47.561218Z",
"url": "https://files.pythonhosted.org/packages/10/98/508fffd0ec8bac7ee2705cf914e6ea433fb14f0b2106b0053a39cf85ef72/sdkwa_whatsapp_chatbot-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 10:53:47",
"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.3"
]
]
},
{
"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
