Python SDK for the SDKWA Messenger HTTP API. Send messages, files, and manage WhatsApp and Telegram accounts programmatically.
- 🚀 Simple & Modern: Clean, type-safe API following Python best practices
- 📱 Multi-Messenger Support: Support for both WhatsApp and Telegram
- 📡 Full API Coverage: Support for all SDKWA API endpoints
- 🔒 Type Safe: Complete type hints for better development experience
- 🪝 Webhook Support: Built-in webhook handling for real-time notifications
- 📁 File Handling: Send files by URL or upload with automatic type detection
- 🔄 Async Support: Optional async/await support for better performance
- 📦 Zero Config: Works out of the box with minimal setup
pip install sdkwa-whatsapp-api-clientBefore you can send or receive messages, you need to authorize your WhatsApp account by scanning a QR code:
from sdkwa import SDKWA
# Initialize the client
client = SDKWA(
id_instance="YOUR_INSTANCE_ID",
api_token_instance="YOUR_API_TOKEN"
)
# Get QR code for authorization
qr_data = client.get_qr()
print(f"QR Code: {qr_data['message']}") # Display this QR code
print(f"Scan this QR code with your WhatsApp mobile app")
# Check authorization state
state = client.get_state_instance()
print(f"Account state: {state['stateInstance']}")
# Wait until state is "authorized" before sending messagesOnce your account is authorized (QR code is scanned), you can start sending messages:
from sdkwa import SDKWA
# Initialize the client (WhatsApp is the default messenger)
client = SDKWA(
id_instance="YOUR_INSTANCE_ID",
api_token_instance="YOUR_API_TOKEN"
)
# Send a text message
response = client.send_message(
chat_id="1234567890@c.us",
message="Hello from SDKWA! 👋"
)
print(f"Message sent with ID: {response['idMessage']}")
# Send a file
response = client.send_file_by_url(
chat_id="1234567890@c.us",
url_file="https://example.com/image.jpg",
file_name="image.jpg",
caption="Check out this image!"
)
# Get account state
state = client.get_state_instance()
print(f"Account state: {state['stateInstance']}")For Telegram, you need to authorize using a confirmation code instead of QR:
from sdkwa import SDKWA
# Create client and use messenger parameter for Telegram calls
client = SDKWA(
id_instance="YOUR_INSTANCE_ID",
api_token_instance="YOUR_API_TOKEN"
)
# Step 1: Authorize with Telegram
# Send confirmation code to your phone number
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")
# Step 3: Now you can send messages
response = client.send_message(
chat_id="1234567890",
message="Hello from SDKWA Telegram! 👋",
messenger="telegram"
)
# Telegram-specific methods
app = client.create_app(
title="My App",
short_name="myapp",
url="https://myapp.com",
description="My awesome Telegram app",
messenger="telegram"
)# Get account settings
settings = client.get_settings()
# Update settings
client.set_settings({
"webhookUrl": "https://your-webhook-url.com",
"delaySendMessagesMilliseconds": 1000
})
# Get QR code for authorization
qr_data = client.get_qr()
# Get account state
state = client.get_state_instance()
print(f"Account state: {state['stateInstance']}")
# Reboot instance
client.reboot()
# Logout
client.logout()# Text message
client.send_message(
chat_id="1234567890@c.us",
message="Hello World!",
quoted_message_id="optional_message_id", # Reply to message
link_preview=True # Enable link previews
)
# Send contact
client.send_contact(
chat_id="1234567890@c.us",
contact={
"phoneContact": 1234567890,
"firstName": "John",
"lastName": "Doe",
"company": "Example Corp"
}
)
# Send location
client.send_location(
chat_id="1234567890@c.us",
name_location="My Location",
address="123 Main St",
latitude=40.7128,
longitude=-74.0060
)# Send file by URL
client.send_file_by_url(
chat_id="1234567890@c.us",
url_file="https://example.com/document.pdf",
file_name="document.pdf",
caption="Important document"
)
# Upload and send file
with open("image.jpg", "rb") as file:
client.send_file_by_upload(
chat_id="1234567890@c.us",
file=file,
file_name="image.jpg",
caption="Photo from vacation"
)
# Download received file
file_data = client.download_file(
chat_id="1234567890@c.us",
id_message="MESSAGE_ID"
)# Get notifications
notification = client.receive_notification()
if notification:
print(f"New notification: {notification}")
# Process notification...
# Delete notification after processing
client.delete_notification(notification['receiptId'])
# Get chat history
history = client.get_chat_history(
chat_id="1234567890@c.us",
count=50
)# Create group
group = client.create_group(
group_name="My Group",
chat_ids=["1234567890@c.us", "0987654321@c.us"]
)
# Get group data
group_info = client.get_group_data("GROUP_ID@g.us")
# Add participants to group
client.add_group_participant(
group_id="GROUP_ID@g.us",
participant_chat_id="1111111111@c.us"
)
# Remove participant from group
client.remove_group_participant(
group_id="GROUP_ID@g.us",
participant_chat_id="1111111111@c.us"
)
# Set group admin
client.set_group_admin(
group_id="GROUP_ID@g.us",
participant_chat_id="1111111111@c.us"
)
# Remove admin rights
client.remove_admin(
group_id="GROUP_ID@g.us",
participant_chat_id="1111111111@c.us"
)
# Update group name
client.update_group_name(
group_id="GROUP_ID@g.us",
group_name="New Group Name"
)
# Set group picture
with open("group_pic.jpg", "rb") as file:
client.set_group_picture("GROUP_ID@g.us", file)
# Leave group
client.leave_group("GROUP_ID@g.us")
# Get contacts
contacts = client.get_contacts()
# Get chats
chats = client.get_chats()
# Get contact info
contact_info = client.get_contact_info("1234567890@c.us")
# Check if number has WhatsApp
has_whatsapp = client.check_whatsapp(1234567890)
# Get avatar
avatar = client.get_avatar("1234567890@c.us")
# Set profile picture
with open("profile_pic.jpg", "rb") as file:
client.set_profile_picture(file)# Mark chat as read
client.read_chat("1234567890@c.us")
# Mark specific message as read
client.read_chat("1234567890@c.us", id_message="MESSAGE_ID")
# Archive chat
client.archive_chat("1234567890@c.us")
# Unarchive chat
client.unarchive_chat("1234567890@c.us")
# Delete message
client.delete_message("1234567890@c.us", "MESSAGE_ID")# Show messages in queue
queue = client.show_messages_queue()
# Clear messages queue
client.clear_messages_queue()# Get last outgoing messages (last 24 hours by default)
outgoing = client.last_outgoing_messages()
# Get last outgoing messages from last 60 minutes
outgoing = client.last_outgoing_messages(minutes=60)
# Get last incoming messages
incoming = client.last_incoming_messages()from flask import Flask, request
from sdkwa import WebhookHandler, WebhookType
app = Flask(__name__)
webhook_handler = WebhookHandler()
# Register event handlers
@webhook_handler.on(WebhookType.INCOMING_MESSAGE_RECEIVED)
def handle_message(notification):
"""Handle incoming message notifications."""
sender_data = notification.get('senderData', {})
message_data = notification.get('messageData', {})
sender = sender_data.get('chatId', 'Unknown')
sender_name = sender_data.get('senderName', 'Unknown')
message_type = message_data.get('typeMessage', 'unknown')
print(f"📥 Incoming message from {sender_name} ({sender})")
if message_type == 'textMessage':
text = message_data.get('textMessageData', {}).get('textMessage', '')
print(f"Message: {text}")
@webhook_handler.on(WebhookType.OUTGOING_MESSAGE_STATUS)
def handle_status(notification):
"""Handle outgoing message status notifications."""
status = notification.get('status', 'unknown')
id_message = notification.get('idMessage', '')
print(f"📤 Message {id_message} status: {status}")
@app.route('/webhook', methods=['POST'])
def webhook():
webhook_handler.handle(request.json)
return "OK"
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000)The SDK provides special methods for Telegram messenger:
# Create a Telegram Business app
app = client.create_app(
title="My Business App",
short_name="mybusiness",
url="https://mybusiness.com",
description="Official business application"
)
print(f"App created with ID: {app['data']['appId']}")# Send confirmation code to phone number
response = client.send_confirmation_code(phone_number=79001234567)
print(f"Confirmation code sent: {response['message']}")
# Sign in with the received code
result = client.sign_in_with_confirmation_code(code="JpkyJeAM8dQ")
print(f"Sign in successful: {result['message']}")export SDKWA_ID_INSTANCE="your_instance_id"
export SDKWA_API_TOKEN="your_api_token"
export SDKWA_API_HOST="https://api.sdkwa.pro" # Optional
export SDKWA_MESSENGER="whatsapp" # Optional: 'whatsapp' or 'telegram', defaults to 'whatsapp'client = SDKWA(
id_instance="your_instance_id",
api_token_instance="your_api_token",
api_host="https://api.sdkwa.pro", # Optional, defaults to official API
messenger="whatsapp", # Optional: 'whatsapp' or 'telegram', defaults to 'whatsapp'
user_id="your_user_id", # Optional, for additional authentication
user_token="your_user_token", # Optional, for additional authentication
timeout=30, # Request timeout in seconds
verify_ssl=True # SSL verification
)from sdkwa import APIError, AuthenticationError, ValidationError
try:
response = client.send_message(
chat_id="invalid_chat_id",
message="Test message"
)
except AuthenticationError:
print("Invalid credentials")
except ValidationError as e:
print(f"Validation error: {e}")
except APIError as e:
print(f"API error: {e}")# Clone the repository
git clone https://github.com/sdkwa/whatsapp-api-client-python.git
cd whatsapp-api-client-python
# Install in development mode
pip install -e .
# Format code
python scripts/dev.py format
# Clean build artifacts
python scripts/dev.py clean
# Build package
python scripts/dev.py build
# Publish to PyPI (requires API token)
python scripts/dev.py publishWe welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the MIT License - see the LICENSE file for details.
- Initial release
- Full API coverage for SDKWA WhatsApp API
- Type-safe implementation
- Webhook support
- Comprehensive documentation and examples