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.36
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.36.tar.gz | 9.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pararamio_bot-3.0.36-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 19.8 kB
Release files / pararamio_bot-3.0.36.tar.gz
| Download URL | pararamio_bot-3.0.36.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df02640ac44a4fa3012f1110c4c64e8f6b9600badc748b75810255edabf97ffb
|
|
BLAKE2b-256 checksum How to use checksums |
f4f52dcff3838338ec89ac64207e825ea0fdca6e9ed662f65f90123e52f53b53
|
| 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.36-py3-none-any.whl
| Download URL | pararamio_bot-3.0.36-py3-none-any.whl |
|---|---|
| Size | 10.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19df93bea649edc99112ef19d8d6b98f68033d0e24bc5e6848f061aae5418c2c
|
|
BLAKE2b-256 checksum How to use checksums |
854a55020f4b248439a19bd010c3770a05c0e649c658c79dc53b923e46cbed46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.14
|
