🚀 Neonize

WhatsApp Automation Made Simple for Python

A powerful Python library built on top of Whatsmeow - enabling seamless WhatsApp automation with enterprise-grade performance

Getting Started • Features • Examples • Documentation • Contributing

</div> <img src="assets/20250607_2254_Futuristic WhatsApp Backend Visualization_simple_compose_01jx5hh659f7bvbqxc8gedz8r8.png" width="100%" alt="Neonize"/>

✨ What is Neonize?

Neonize is a cutting-edge Python library that transforms WhatsApp automation from complex to simple. Built on top of the robust Whatsmeow Go library, it delivers enterprise-grade performance with Python's ease of use and developer-friendly API.

🎯 Why Choose Neonize?

🔥 High Performance - Built with Go backend for maximum speed and efficiency
🐍 Python Native - Seamless integration with your existing Python ecosystem
🛡️ Enterprise Ready - Production-tested with robust error handling and reliability
⚡ Real-time - Handle messages, media, and events in real-time with async support
🔧 Easy Integration - Simple, intuitive API design for rapid development
📚 Well Documented - Comprehensive documentation with practical examples

🌟 Features

Core Messaging

✅ Send and receive text messages
✅ Handle media files (images, videos, documents, audio)
✅ Group management and operations
✅ Real-time message events
✅ Message receipts and status tracking

Advanced Capabilities

🔐 End-to-end encryption support
🎯 Contact and user information retrieval
📞 Call event handling
🔔 Presence and typing indicators
📊 Polls and interactive messages
🚫 Blocklist management

Developer Experience

🔄 Event-driven architecture
📊 Built-in logging and debugging
🗄️ SQLite and PostgreSQL database support
⚡ Both synchronous and asynchronous APIs
🧪 Comprehensive examples and documentation

💎 Sponsors

We are grateful to our sponsors who help make Neonize possible. Their support enables us to continue developing and maintaining this open-source project for the community.

<a href="https://github.com/OwlFeedMe"><img src="https://github.com/OwlFeedMe.png" width="60px" alt="User avatar: FeedMe" /></a><a href="https://github.com/Seikened"><img src="https://github.com/Seikened.png" width="60px" alt="User avatar: Fernando Leon Franco" /></a>

🤝 Become a Sponsor

Your sponsorship helps us:

⚡ Maintain and improve Neonize
🐛 Fix bugs and add new features
📚 Create better documentation
🔧 Provide community support
🚀 Keep the project free and open-source

Become a Sponsor →

Thank you to all our sponsors for believing in Neonize and supporting open-source development! 🙏

🚀 Getting Started

Prerequisites

Python 3.8 or higher
Go 1.19+ (for building from source)

Installation

pip install neonize

Quick Start

from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

# Initialize client
client = NewClient("your_bot_name")

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("🎉 Bot connected successfully!")

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    if event.message.conversation == "hi":
        client.reply_message("Hello! 👋", event.message)

# Start the bot
client.connect()
event.wait()  # Keep running

Async Version

import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import MessageEv, ConnectedEv

client = NewAClient("async_bot")

@client.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    if event.Message.conversation == "ping":
        await client.reply_message("pong! 🏓", event)

async def main():
    await client.connect()
    await client.idle()  # Keep receiving events

asyncio.run(main())

!!! important "Python 3.10+ Event Loop" Neonize uses asyncio.run() as the standard entry point. The event loop is automatically obtained via asyncio.get_running_loop() inside connect(). Do not use the deprecated asyncio.get_event_loop() or loop.run_until_complete() — these raise errors on Python 3.12+.

💡 Examples

📱 Basic Client Setup

from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event
import logging

# Enable logging for debugging
logging.basicConfig(level=logging.INFO)

# Initialize the WhatsApp client
client = NewClient(
    name="my-whatsapp-bot",
    database="./neonize.db"
)

# Handle successful connection
@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("🎉 Successfully connected to WhatsApp!")
    print(f"📱 Device: {event.device}")

# Start the client
client.connect()
event.wait()

💬 Sending Messages

from neonize.utils import build_jid

# Send simple text message
jid = build_jid("1234567890")
client.send_message(jid, text="Hello from Neonize! 🚀")

# Send image with caption
with open("image.jpg", "rb") as f:
    image_data = f.read()

image_msg = client.build_image_message(
    image_data,
    caption="Check out this amazing image! 📸",
    mime_type="image/jpeg"
)
client.send_message(jid, message=image_msg)

# Send document file
with open("document.pdf", "rb") as f:
    doc_data = f.read()

doc_msg = client.build_document_message(
    doc_data,
    filename="document.pdf",
    caption="Here is the document you requested",
    mime_type="application/pdf"
)
client.send_message(jid, message=doc_msg)

🎭 Message Event Handling

from neonize.events import MessageEv, ReceiptEv, PresenceEv
from datetime import datetime

# Handle incoming text messages
@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    message_text = event.message.conversation
    sender_jid = event.info.message_source.sender
    chat_jid = event.info.message_source.chat
    
    print(f"📨 Received from {sender_jid}: {message_text}")
    
    # Auto-reply functionality
    if message_text and message_text.lower() == "hello":
        client.send_message(chat_jid, text="Hello there! 👋")
    elif message_text and message_text.lower() == "help":
        help_text = """
🤖 *Bot Commands:*
• hello - Get a greeting
• help - Show this help message
• time - Get current time
• joke - Get a random joke
"""
        client.send_message(chat_jid, text=help_text)
    elif message_text and message_text.lower() == "time":
        current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        client.send_message(chat_jid, text=f"🕐 Current time: {current_time}")

# Handle message receipts (delivery status)
@client.event(ReceiptEv)
def on_receipt(client: NewClient, event: ReceiptEv):
    print(f"📧 Message {event.receipt.type}: {event.message_ids}")

# Handle typing indicators
@client.event(PresenceEv)
def on_presence(client: NewClient, event: PresenceEv):
    chat = event.message_source.chat
    participant = event.message_source.sender
    print(f"💬 {participant} is {event.presence} in {chat}")

👥 Group Management

from neonize.utils import build_jid

# Create a new group
participants = [
    build_jid("1234567890"),
    build_jid("0987654321"),
]

group_info = client.create_group(
    "My Awesome Group 🚀",
    participants
)
print(f"🎉 Group created: {group_info.jid}")

# Get group information
group_info = client.get_group_info(group_jid)
print(f"📋 Group Name: {group_info.group_name}")
print(f"📝 Description: {group_info.group_desc}")
print(f"👥 Participants: {len(group_info.participants)}")

# Add participants to group
client.update_group_participants(
    group_jid,
    [user_jid],
    "add"
)

# Remove participants from group
client.update_group_participants(
    group_jid,
    [user_jid],
    "remove"
)

# Update group name
client.update_group_name(
    group_jid,
    "New Group Name 🎯"
)

# Update group description
client.update_group_description(
    group_jid,
    "This is our updated group description"
)

🔍 Contact & Profile Management

# Get user profile information
profile = client.get_profile_picture(
    user_jid,
    full_resolution=True
)
print(f"👤 Profile picture URL: {profile.url}")
print(f"🆔 Profile ID: {profile.id}")

# Update your own status
client.set_presence("available")
print("✅ Status updated to available")

# Check if contacts are on WhatsApp
contacts = ["1234567890", "0987654321", "1122334455"]
registered_contacts = client.is_on_whatsapp(contacts)

for contact in registered_contacts:
    if contact.is_in:
        print(f"✅ {contact.jid} is on WhatsApp")
    else:
        print(f"❌ {contact.query} is not on WhatsApp")

📊 Polls & Interactive Messages

from neonize.utils.enum import VoteType

# Create a poll
poll_msg = client.build_poll_vote_creation(
    "What's your favorite programming language?",
    ["Python 🐍", "Go 🚀", "JavaScript 💛", "Rust 🦀"],
    VoteType.SINGLE_SEL

Neonize

Install / Use

README