Documentation Index
Fetch the complete documentation index at: https://mintlify.com/nicotine-plus/nicotine-plus/llms.txt
Use this file to discover all available pages before exploring further.
The Chat module provides functionality for chat rooms and private messaging, including room management, message handling, and user tracking.
Overview
The Chat module consists of two main classes:
- ChatRooms: Public and private chat room management
- PrivateChat: Private messaging between users
ChatRooms Class
Initialization
from pynicotine.chatrooms import ChatRooms
chatrooms = ChatRooms()
Room Management
join_room()
Joins a chat room.
chatrooms.join_room(room_name, private=False)
Whether this is a private room
# Join public room
chatrooms.join_room("Music")
# Join private room
chatrooms.join_room("private-room-123", private=True)
leave_room()
Leaves a chat room.
chatrooms.leave_room(room_name)
Name of the room to leave
get_joined_rooms()
Returns list of currently joined rooms.
joined_rooms = chatrooms.get_joined_rooms()
List of room names currently joined
is_joined()
Checks if currently in a room.
is_in_room = chatrooms.is_joined("Music")
True if currently in the room
Message Methods
send_message()
Sends a message to a chat room.
chatrooms.send_message(room_name, message)
# Send a message
chatrooms.send_message("Music", "Anyone have recommendations for jazz albums?")
send_me_action()
Sends an action message (like “/me” in IRC).
chatrooms.send_me_action(room_name, action)
# Send action message
chatrooms.send_me_action("Music", "is listening to jazz")
get_room_users()
Returns users in a room.
users = chatrooms.get_room_users(room_name)
List of usernames in the room
get_user_stats()
Returns statistics for a user in a room.
stats = chatrooms.get_user_stats(room_name, username)
Dictionary with “avgspeed”, “files”, “dirs” keys
stats = chatrooms.get_user_stats("Music", "user123")
print(f"Files: {stats['files']}")
print(f"Speed: {stats['avgspeed']} KB/s")
get_user_status()
Returns a user’s status in a room.
status = chatrooms.get_user_status(room_name, username)
Status code: 0=offline, 1=away, 2=online
Room List
request_room_list()
Requests list of available rooms from server.
chatrooms.request_room_list()
get_room_list()
Returns cached list of available rooms.
rooms = chatrooms.get_room_list()
List of tuples: (room_name, num_users)
# Get and display room list
rooms = chatrooms.get_room_list()
for room_name, num_users in rooms:
print(f"{room_name}: {num_users} users")
Tickers
set_ticker()
Sets your ticker message in a room.
chatrooms.set_ticker(room_name, ticker_message)
# Set ticker
chatrooms.set_ticker("Music", "Check out my collection!")
get_tickers()
Returns ticker messages in a room.
tickers = chatrooms.get_tickers(room_name)
Dictionary mapping usernames to ticker messages
PrivateChat Class
Initialization
from pynicotine.privatechat import PrivateChat
privatechat = PrivateChat()
Messaging
send_message()
Sends a private message to a user.
privatechat.send_message(username, message)
Username to send message to
# Send private message
privatechat.send_message("user123", "Hey, thanks for sharing those files!")
send_me_action()
Sends an action message privately.
privatechat.send_me_action(username, action)
Conversation Management
get_users()
Returns list of users you have private conversations with.
users = privatechat.get_users()
get_messages()
Returns message history with a user.
messages = privatechat.get_messages(username)
Username to get messages for
List of message dictionaries
clear_messages()
Clears message history with a user.
privatechat.clear_messages(username)
Events
The Chat module emits events for incoming messages and room activity:
from pynicotine.events import events
# Room message received
events.connect("room-message", on_room_message)
# Private message received
events.connect("private-message", on_private_message)
# User joined room
events.connect("user-joined-room", on_user_joined)
# User left room
events.connect("user-left-room", on_user_left)
def on_room_message(room_name, username, message, timestamp):
print(f"[{room_name}] {username}: {message}")
def on_private_message(username, message, timestamp):
print(f"[PM from {username}] {message}")
# Auto-reply example
if "thanks" in message.lower():
privatechat.send_message(username, "You're welcome!")
def on_user_joined(room_name, username):
print(f"{username} joined {room_name}")
def on_user_left(room_name, username):
print(f"{username} left {room_name}")
Complete Example
from pynicotine.chatrooms import ChatRooms
from pynicotine.privatechat import PrivateChat
from pynicotine.events import events
from pynicotine.core import core
# Initialize chat modules
chatrooms = ChatRooms()
privatechat = PrivateChat()
# Track room activity
room_messages = {}
def on_room_message(room_name, username, message, timestamp):
if room_name not in room_messages:
room_messages[room_name] = []
room_messages[room_name].append({
'username': username,
'message': message,
'timestamp': timestamp
})
print(f"[{room_name}] {username}: {message}")
# Respond to mentions
if core.login_username in message:
chatrooms.send_message(
room_name,
f"{username}: Yes, I'm here!"
)
def on_private_message(username, message, timestamp):
print(f"[PM from {username}] {message}")
# Auto-responder
if message.lower() == "hi":
privatechat.send_message(username, "Hello! How can I help?")
def on_user_joined(room_name, username):
# Welcome new users
chatrooms.send_message(room_name, f"Welcome, {username}!")
# Get user stats
stats = chatrooms.get_user_stats(room_name, username)
print(f"{username} has {stats['files']} files shared")
# Connect events
events.connect("room-message", on_room_message)
events.connect("private-message", on_private_message)
events.connect("user-joined-room", on_user_joined)
# Join rooms
chatrooms.join_room("Music")
chatrooms.join_room("Jazz")
chatrooms.join_room("Electronic")
# Set ticker
chatrooms.set_ticker("Music", "Sharing 10,000+ FLAC albums!")
# Send messages
chatrooms.send_message("Music", "Hello everyone!")
chatrooms.send_me_action("Music", "is ready to chat")
# Get room info
joined = chatrooms.get_joined_rooms()
print(f"Joined rooms: {joined}")
for room in joined:
users = chatrooms.get_room_users(room)
print(f"{room}: {len(users)} users online")
# Send private message
privatechat.send_message("friend123", "Hey, want to trade music?")
# List room activity
rooms = chatrooms.get_room_list()
print("\nAvailable rooms:")
for room_name, num_users in sorted(rooms, key=lambda x: x[1], reverse=True)[:10]:
print(f" {room_name}: {num_users} users")
Chat Commands
Many chat applications support special commands:
def process_chat_command(room_name, command):
"""Process slash commands in chat"""
if command.startswith("/me "):
action = command[4:]
chatrooms.send_me_action(room_name, action)
elif command.startswith("/join "):
new_room = command[6:]
chatrooms.join_room(new_room)
elif command.startswith("/part") or command.startswith("/leave"):
chatrooms.leave_room(room_name)
elif command == "/users":
users = chatrooms.get_room_users(room_name)
print(f"Users in {room_name}: {', '.join(users)}")
elif command == "/rooms":
rooms = chatrooms.get_room_list()
for name, count in rooms[:20]:
print(f"{name} ({count})")
else:
chatrooms.send_message(room_name, command)
# Usage
process_chat_command("Music", "Hello everyone!")
process_chat_command("Music", "/me is listening to jazz")
process_chat_command("Music", "/users")
Best Practices
- Join relevant rooms to find content and connect with users
- Use tickers to advertise your shares
- Be respectful and follow room rules
- Handle incoming messages asynchronously to avoid blocking
- Store message history for conversation context
- Implement rate limiting to avoid flooding
- Use private messages for one-on-one conversations
- Monitor room lists to discover active communities