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:
- URL key — the first 8 chars of the bot secret must be present in the request path. Requests with a wrong key get
404. - 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:
| Field | Type | Description |
|---|---|---|
user_id |
int |
Sender user ID |
user_unique_name |
str |
Sender unique name |
post_no |
int |
Post number in the chat |
chat_id |
int |
Chat ID |
text |
str |
Message text |
organization_id |
int | None |
Organization ID (optional) |
text_parsed |
list[dict] | None |
Parsed text structure |
reply_no |
int | None |
Replied-to post number |
reply_text |
str | None |
Replied-to post text |
file_guid |
str | None |
Attached file GUID |
file_name |
str | None |
Attached file name |
attachments |
list[str] | None |
List of attachment identifiers |
WebhookAction — user clicked a bot:// link:
| Field | Type | Description |
|---|---|---|
user_id |
int |
User who clicked |
chat_id |
int |
Chat ID |
post_no |
int |
Post number |
organization_id |
int | None |
Organization ID (optional) |
action |
str |
Action name from the link |
params |
dict[str, str] |
Action parameters |
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
| Route | Description |
|---|---|
POST /{url_key} |
Receive message webhooks |
POST /{url_key}/act |
Receive action webhooks |
Requirements
- Python >= 3.11
- aiohttp >= 3.9
- pydantic >= 2.0
1 maintainer
Metadata
1 maintainer
Release files for pararamio-bot 3.0.37
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pararamio_bot-3.0.37.tar.gz | 9.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pararamio_bot-3.0.37-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 19.8 kB
Release files / pararamio_bot-3.0.37.tar.gz
| Download URL | pararamio_bot-3.0.37.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
40ee14f63a8f4b893d84e87bfa398e7c8434865441cb5f162cd0747a89edaa73
|
|
BLAKE2b-256 checksum How to use checksums |
846ce52c19cc10e0c6077305501ab71ada5b030cd08820d5f2925dc29a446e73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.14
|
Release files / pararamio_bot-3.0.37-py3-none-any.whl
| Download URL | pararamio_bot-3.0.37-py3-none-any.whl |
|---|---|
| Size | 10.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9de61e15dbd6e64c2f97f4857b73263f58f2cce263f26d59c4847818a21fa71d
|
|
BLAKE2b-256 checksum How to use checksums |
f5c14b3f15bd1ebd539346509b01c75d63694550225ef59428a27b30b2d89323
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.14
|
