Rolespace Python SDK

Minimal client for the Rolespace bot API. Requires Python 3.8+ and requests.

Install

Drop rolespace.py into your project, or:

pip install rolespace

Quick start

from rolespace import Rolespace

# Reads ROLESPACE_BOT_TOKEN from your environment.
rs = Rolespace.from_env()

me = rs.me()
print(f"Logged in as {me['bot']['username']} (#{me['bot']['id']})")

# Send a message:
rs.send_message(server_id, channel_id, "Hello from my bot!")

# Listen for interactions (button clicks, modal submits, etc.):
for ix in rs.interactions():
    if ix["customId"] == "book":
        rs.respond(ix["id"], {"type": "message", "content": "Booked!", "ephemeral": True})

Webhook signature verification

from flask import Flask, request, abort
from rolespace import Rolespace
import os, json

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]

@app.post("/webhook")
def webhook():
    raw = request.get_data()  # raw bytes — NOT request.json
    sig = request.headers.get("X-Rolespace-Signature", "")
    if not Rolespace.verify_webhook(raw, sig, SECRET):
        abort(401)
    event = json.loads(raw)
    # ...handle event...
    return ("", 204)

Important: use request.get_data() — request.json re-serializes the body and the signature check will fail.

What this SDK does for you

• Loads the token from ROLESPACE_BOT_TOKEN so you don't hardcode it
• Retries 429s with exponential backoff (honors Retry-After)
• Hides the bot token from repr(client)
• Verifies webhook signatures with hmac.compare_digest (constant-time)
• Generator over /interactions — no manual polling loop or cursor bookkeeping

API