pyokbot 1.0.0

A Python library for creating bots in Odnoklassniki (ok.ru) messenger via WebSocket

Python library for Odnoklassniki (ok.ru) bots — WebSocket, async, instant

⚠️ Alpha stage — works, expect rough edges

---

📦 What is pyokbot?

pyokbot is the only Python library for building bots in Odnoklassniki (ok.ru) messenger. It speaks the raw WebSocket protocol that OK.ru's own clients use — no HTTP polling, no delays, no browser automation.

import asyncio
from pyokbot import Vanus

async def main():
    bot = Vanus("YOUR_AUTHCODE")
    await bot.run()

    @bot.on_message(commands=["ping"])
    async def ping(message):
        await bot.send_reply(message, "pong!")

    await bot.polling()

asyncio.run(main())

A bot that replies to /ping with pong! in ~10 lines of code.

---

✨ Features

Feature	Description
⚡ Real-time	Persistent WebSocket — messages arrive instantly
🔧 Commands	@bot.on_message(commands=["start"]) handles /start
🎯 Filters	Route by content type, text, or sender (user/bot)
🖼️ Media	Send photos, videos, files, voice messages
📝 HTML	Bold, italic, code, headings, links with parse_mode="html"
👥 Chat admin	Pin, edit, delete, clear, change title/photo, kick
⌨️ Typing	Show "bot is typing..." before responding
🔁 Auto-reconnect	Exponential backoff when connection drops
💾 Cache	User profiles cached with 1-hour TTL
🧹 Clean shutdown	Ctrl+C handled gracefully

---

🚀 Quick start

Install

pip install pyokbot

Python 3.9+. You need an AUTHCODE cookie from ok.ru — see the docs for how to get one.

Echo bot

import asyncio
from pyokbot import Vanus

async def main():
    bot = Vanus("YOUR_AUTHCODE")
    await bot.run()

    @bot.on_message(filters="user")
    async def echo(message):
        await bot.send_reply(message, f"You said: {message.text}")

    await bot.polling()

asyncio.run(main())

python bot.py

---

🎮 What it can do

📋 Commands — trigger on /start, /help, etc.

@bot.on_message(commands=["start"])
async def start(message):
    await bot.send_message(message.chat.id, "Welcome!")

@bot.on_message(commands=["help"])
async def help(message):
    await bot.send_message(message.chat.id, "Available: /start, /help, /ping")

🎯 Filters — route by content type or text

@bot.on_message(filters="user", content_types=["photo"])
async def on_photo(message):
    await bot.send_reply(message, "Nice pic!")

@bot.on_message(filters="user", text="hello")
async def on_hello(message):
    await bot.send_reply(message, "Hi there!")

🖼️ Media — send photos, videos, files, voice

await bot.send_photo(message.chat.id, "https://example.com/cat.jpg", caption="cat")
await bot.send_video(message.chat.id, "video.mp4")
await bot.send_file(message.chat.id, "report.pdf", title="Report")
await bot.send_voice(message.chat.id, "message.ogg")

📝 HTML formatting — bold, italic, code, links

await bot.send_message(
    message.chat.id,
    "<b>bold</b> <i>italic</i> <code>code</code> <a href='https://ok.ru'>link</a>",
    parse_mode="html",
)

👥 Chat management — pin, edit, kick, clear

await bot.pin_chat_message(chat_id, msg_id)
await bot.edit_message_text(chat_id, msg_id, "new text")
await bot.clear_chat_history(chat_id, for_all=True)
await bot.change_chat_title(chat_id, "New Name")
await bot.delete_member(chat_id, member_id="12345")

⌨️ Typing indicator — "bot is typing..."

await bot.writing_emulation(message.chat.id)
await asyncio.sleep(1)
await bot.send_reply(message, "done!")

---

🧠 How handlers work

Handlers are checked in registration order. The first match wins.

@bot.on_message(commands=["start"])    # checked first
@bot.on_message(commands=["help"])     # checked second
@bot.on_message(filters="user")        # catch-all, checked last

The message object has attribute-style access:

Field	Type	Description
message.text	str	Text content
message.chat.id	str	Chat ID
message.user.id	str	Sender ID
message.id	str	Message ID
message.photo	list	Photo attachments
message.video	list	Video attachments
message.audio	dict	Voice attachment
message.document	dict	File attachment
message.is_reply	bool	Is this a reply?
message.reply	dict	Replied-to message

---

🔧 Examples

Ready-to-run bots in the examples/ directory:

Bot	What it does
echobot.py	Echo commands, photos, videos, text
media_bot.py	Send photos, videos, files, voice
filter_demo_bot.py	All filter types (commands, text, content-type)
html_demo_bot.py	HTML formatting with all tags
chat_admin_bot.py	Pin, edit, clear, kick, change title

python examples/echobot.py YOUR_AUTHCODE

---

📚 Documentation

Full docs: SangoAlgo.github.io/pyokbot

• Installation guide
• Quick start
• API reference
• Examples
• FAQ

---

📄 License

MIT — see LICENSE.