Neonize Python WhatsApp Library Skill

Overview

Neonize is a Python library for WhatsApp automation built on top of the Whatsmeow Go library. It provides enterprise-grade performance with a developer-friendly Python API.

• Repository: krypton-byte/neonize
• Documentation: krypton-byte.github.io/neonize
• License: Apache 2.0
• Python: 3.8+
• Latest Version: 0.3.15+

Installation

pip install neonize

Core Concepts

JID (WhatsApp Identifier)

WhatsApp uses JIDs (Jabber IDs) to identify users, groups, and channels:

from neonize.utils import build_jid

# Phone number to JID conversion
user_jid = build_jid("1234567890")           # -> "1234567890@s.whatsapp.net"
# For channels, WhatsApp uses a different format
channel_jid = "channel_jid@s.whatsapp.net"    # Channel JIDs end with @newsletter

Client Setup

Synchronous Client

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

logging.basicConfig(level=logging.INFO)

client = NewClient(
    name="my-bot",        # Display name for the client
    database="./neonize.db"  # SQLite database for session storage
)

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print(f"Connected! Device: {event.device}")

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

Asynchronous Client

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 and event.Message.conversation.lower() == "ping":
        await client.reply_message("pong!", event)

async def main():
    await client.connect()
    await client.idle()

asyncio.run(main())

Sending Messages

Basic Text Message

from neonize.utils import build_jid

# Send to a user
user_jid = build_jid("1234567890")
client.send_message(user_jid, text="Hello from Neonize! 🚀")

# Reply to an existing message
client.reply_message("Hello!", event.Message)

Media Messages

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

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

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

doc_msg = client.build_document_message(
    doc_data,
    caption="Here's the document",
    file_name="document.pdf",
    mime_type="application/pdf"
)
client.send_message(jid, message=doc_msg)

Receiving Messages

Message Event Handler

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

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    # Extract message content
    message_text = event.Message.conversation  # Text messages
    # For other message types, check:
    # - event.Message.extended_text_message  (text with link preview)
    # - event.Message.image_message          (image with caption)
    # - event.Message.document_message       (document)

    # Get message source info
    sender_jid = event.Info.MessageSource.Sender
    chat_jid = event.Info.MessageSource.Chat

    print(f"Message from {sender_jid}: {message_text}")

    # Respond to specific commands
    if message_text:
        if message_text.lower() == "hello":
            client.send_message(chat_jid, text="Hello there! 👋")
        elif 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}")
        elif message_text.lower() == "help":
            client.send_message(chat_jid, text="Available commands: hello, help, time")

Other Event Types

@client.event(ReceiptEv)
def on_receipt(client: NewClient, event: ReceiptEv):
    print(f"Receipt for {event.Recieved.MessageIDs}: {event.Recieved.Type}")

@client.event(PresenceEv)
def on_presence(client: NewClient, event: PresenceEv):
    sender = event.Info.MessageSource.Sender
    presence_type = event.Presence
    print(f"{sender} is {presence_type}")

Working with Channels (Newsletters)

WhatsApp Channels are broadcast-only communication channels. Unlike groups where multiple members can message, channels have a single entity (admin) that broadcasts content to subscribers.

Getting Channel Messages

# Get recent messages from a channel
# channel_jid format: "channelID@s.whatsapp.net" or "channelID@newsletter"
messages = client.get_newsletter_messages(channel_jid, count=20)

for msg in messages:
    print(f"Message ID: {msg.MessageID}")
    print(f"Content: {msg.conversation or msg.extended_text_message}")
    print(f"Timestamp: {msg.Timestamp}")

Following/Subscribing to a Channel

# Subscribe to receive updates from a channel
client.follow_newsletter(channel_jid)

# Unsubscribe from a channel
client.unfollow_newsletter(channel_jid)

Sending Messages to a Channel

# Send a message to a channel you admin
client.send_message(channel_jid, text="Hello channel subscribers! 📢")

Getting Channel Info

# Get details about a channel
channel_info = client.get_newsletter_info(channel_jid)
print(f"Name: {channel_info.name}")
print(f"Description: {channel_info.description}")
print(f"Subscriber count: {channel_info.subscribers}")

Working with Groups

Create a Group

from neonize.utils import build_jid

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

group_info = client.create_group(
    "My Awesome Group",
    participants
)
group_jid = group_info.JID

Group Operations

# Get group info
group_info = client.get_group_info(group_jid)

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

# Remove participants
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, "Group description here")

# Get group invite link
invite_link = client.get_group_invite_link(group_jid)

User and Contact Management

# Get user's profile picture
profile = client.get_profile_picture(user_jid, full_resolution=True)

# Update your presence
client.set_presence("available")  # "available", "unavailable", "typing"

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

for contact in registered:
    if contact.IsIn:
        print(f"{contact.JID} is on WhatsApp")

Polls and Interactive Messages

from neonize.utils.enum import VoteType

# Create a poll
poll_msg = client.build_poll_vote_creation(
    "What's your favorite language?",
    ["Python", "Go", "JavaScript", "Rust"],
    VoteType.SINGLE_SELECT
)
client.send_message(chat_jid, message=poll_msg)

# Handle poll responses
@client.event(MessageEv)
def on_poll_response(client: NewClient, event: MessageEv):
    if event.Message.poll_update_message:
        voter = event.Info.MessageSource.Sender
        selected = event.Message.poll_update_message.Vote.SelectedOptions
        print(f"{voter} voted for: {selected}")

Complete Bot Example

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

logging.basicConfig(level=logging.INFO)

client = NewClient("whatsapp-bot", database="./bot.db")

@client.event(ConnectedEv)
def on_connected(client: NewClient, ev: ConnectedEv):
    print("Bot connected to WhatsApp!")
    print(f"Device: {ev.Device}")

@client.event(MessageEv)
def on_message(client: NewClient, ev: MessageEv):
    msg = ev.Message
    chat = ev.Info.MessageSource.Chat

    text = msg.conversation or (msg.extended_text_message.text if msg.extended_text_message else None)

    if not text:
        return

    text = text.strip().lower()

    if text == "hi" or text == "hello":
        client.send_message(chat, text="Hello! 👋 I'm a WhatsApp bot.")

    elif text == "help":
        help_text = """
Available commands:
- hi/hello: Greeting
- help: Show this help
- ping: Check if bot is alive
- time: Show current time
        """
        client.send_message(chat, text=help_text.strip())

    elif text == "ping":
        client.send_message(chat, text="Pong! 🏓")

    elif text == "time":
        from datetime import datetime
        current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        client.send_message(chat, text=f"Current time: {current_time}")

# Run the bot
print("Starting WhatsApp bot...")
client.connect()
event.wait()

Multi-Device Support

Neonize supports multiple simultaneous client sessions:

# Create multiple clients
bot1 = NewClient("bot-1", database="./bot1.db")
bot2 = NewClient("bot-2", database="./bot2.db")

# Each client can have different event handlers
@bot1.event(MessageEv)
def on_bot1_message(client: NewClient, event: MessageEv):
    client.send_message(event.Info.MessageSource.Chat, text="This is Bot 1!")

@bot2.event(MessageEv)
def on_bot2_message(client: NewClient, event: MessageEv):
    client.send_message(event.Info.MessageSource.Chat, text="This is Bot 2!")

# Connect both
bot1.connect()
bot2.connect()
event.wait()

Database Support

SQLite (Default)

client = NewClient("bot", database="./neonize.db")  # SQLite by default

PostgreSQL (Production)

# PostgreSQL connection string
db_url = "postgresql://user:password@localhost:5432/neonize"
client = NewClient("bot", database=db_url)

Event Reference

ConnectedEv

DisconnectedEv

MessageEv

ReceiptEv

PresenceEv

GroupInviteEv

CallEv

API Reference

Client Methods

connect()

disconnect()

send_message(jid, text=, message=)

reply_message(text, message)

build_image_message()

build_document_message()

build_poll_vote_creation()

create_group()

get_group_info()

update_group_participants()

get_newsletter_messages()

follow_newsletter()

unfollow_newsletter()

get_profile_picture()

is_on_whatsapp()

Resources

• Official Documentation
• GitHub Repository
• Medium Guide: Building a WhatsApp Bot
• Example Bot
• Neonize Examples