bulletins

Python SDK for the Bulletins API. Async client, SSE streaming, and a declarative bot framework.

Install

uv add bulletins-sdk

Quick start

Client

import asyncio
from bulletins import BulletinsClient

async def main():
    client = BulletinsClient("bk_...", base_url="https://bulletins.no")

    async with client:
        await client.resolve()  # auto-resolves party + integration from key
        threads = await client.list_threads()
        for t in threads:
            print(f"{t.name} ({t.status})")

        await client.send_message(threads[0].id, "Hello from Python")

asyncio.run(main())

SSE streaming

async with client.stream_party() as stream:
    async for event in stream:
        print(f"[{event['type']}] {event.get('senderName')}: {event['content']}")

Bot

Declarative bot with auto-registration of event types and actions:

import asyncio
from bulletins import Bot, EventTypeSpec, ActionSpec

bot = Bot(
    "Ping Bot",
    event_types=[
        EventTypeSpec("bot:pong",
            content_schema={"message": {"type": "string"}},
            display_hint={"label": "Pong"}),
    ],
    actions=[
        ActionSpec("Approve", color="success"),
        ActionSpec("Reject", color="destructive"),
    ],
)

@bot.on("message")
async def handle(event, client):
    body = (event.content or {}).get("body", "")
    if body.startswith("!ping"):
        await client.send_message(event.thread_id, "pong")

@bot.on("action_invoked")
async def on_action(event, client):
    key = (event.content or {}).get("key", "")
    match key:
        case "Approve": ...
        case "Reject": ...

asyncio.run(bot.start(api_key="bk_...", base_url="https://bulletins.no"))

Create the integration and API key in the Bulletins settings UI. The bot auto-resolves its party and integration from the API key, registers event types and actions on startup, and dispatches incoming events to handlers.

Action IDs are available via bot.action_ids after start — pass them to create_event to attach inline controls:

await client.create_event(thread_id, "bot:pong", {"message": "pong"},
    actions=[bot.action_ids["Approve"], bot.action_ids["Reject"]])

API

BulletinsClient

Bot

ActionSpec

EventTypeSpec

Requirements

Python 3.12+, httpx.