What problem does this solve?
Backend systems often need to send notifications, alerts, or reports across multiple delivery channels that fail in different and unpredictable ways.
Typical issues include:
- One provider being temporarily unavailable
- Partial delivery across channels
- Silent failures without clear error signals
broadcastio acts as a single orchestration layer that attempts delivery across providers with explicit failure semantics.
What broadcastio is (and is not)
It is
- A Python orchestration layer for outbound messages
- A way to attempt delivery across one or more providers
- A library with ordered fallback and retry logic
- Designed for alerts, reports, and backend-triggered notifications
It is not
- A chatbot framework
- An inbound message handler
- A WhatsApp automation system by itself
Typical usage flow
- Register one or more delivery providers
- Define a message payload
- Dispatch via the orchestrator
- Inspect delivery result and failures explicitly
The caller always receives a deterministic result object — even when delivery fails.
Minimal example
from broadcastio.core.orchestrator import Orchestrator
from broadcastio.providers.whatsapp import WhatsAppProvider
from broadcastio.core.message import Message
wa = WhatsAppProvider("http://localhost:3000")
orch = Orchestrator([wa])
result = orch.send(
Message(
recipient="6281234567890",
content="Service is down"
)
)
print(result.success)
Failure-aware by design
broadcastio distinguishes clearly between:
- Exceptions → configuration or programmer errors
- Delivery results → delivery was attempted but failed
if not result.success:
print(result.error.code, result.error.message)
This makes failures observable and actionable instead of silent.
When should you use this?
broadcastio is well-suited for:
- Infrastructure alerts
- Scheduled backend reports
- Operational notifications
- Systems that require defensive delivery guarantees
It is intentionally not optimized for conversational flows.
Providers & architecture note
Providers (WhatsApp, Email, etc.) are implemented as adapters.
For example:
- WhatsApp delivery relies on an external Node.js service based on WhatsApp Web
- This service is not bundled with the Python package
The provider layer is intentionally swappable.
Project status
- Status: Alpha
- APIs may evolve before 1.0.0
- Core orchestration logic is tested and stable
Source code and full documentation are available in the case study.