pararamio-bot

Async webhook server for pararam.io bot events.

Installation

pip install pararamio-bot

Quick Start

import asyncio
import os

from pararamio_bot import WebhookMessage, WebhookServer


async def on_message(message: WebhookMessage) -> None:
    print(f"@{message.user_unique_name}: {message.text}")


async def main() -> None:
    async with WebhookServer(bot_secret=os.environ["BOT_SECRET"], port=8080) as server:
        server.on_message(on_message)
        await asyncio.Event().wait()


asyncio.run(main())

Configure your bot's webhook URL in pararam.io to http://<host>:8080/<url_key>, where <url_key> is the first 8 characters of your bot secret.

Security

Every incoming request is verified in two steps:

1. URL key — the first 8 chars of the bot secret must be present in the request path. Requests with a wrong key get 404.
2. X-Signature — HMAC-SHA256 signature of the request body, verified against the bot secret. Missing or invalid signature returns 401.

Both checks are always enabled and cannot be disabled.

API

WebhookServer

server = WebhookServer(
    bot_secret="...",  # Full bot secret from pararam.io
    host="0.0.0.0",    # Bind address (default)
    port=8080,          # Listen port (default)
)

Context manager:

async with WebhookServer(bot_secret="...") as server:
    server.on_message(handler)
    # server is running

Manual start/stop:

await server.start()
# ...
await server.stop()

Callbacks

Register async callbacks for incoming events:

server.on_message(callback)  # Called for each incoming message
server.on_action(callback)   # Called for bot:// link clicks

Multiple callbacks can be registered; they are called sequentially.

Models

WebhookMessage — incoming message from a user:

WebhookAction — user clicked a bot:// link:

Utility Functions

from pararamio_bot import extract_url_key, extract_api_key, make_signature, verify_signature

# Get the URL key (first 8 chars) from a bot secret
url_key = extract_url_key(bot_secret)

# Get the API key portion (chars 20+ for secrets > 50 chars)
api_key = extract_api_key(bot_secret)

# Compute / verify HMAC-SHA256 signatures
sig = make_signature(body, secret)
is_valid = verify_signature(body, sig, secret)

HTTP Endpoints

Requirements

• Python >= 3.11
• aiohttp >= 3.9
• pydantic >= 2.0