Emergency-grade alerting and response
Command every call, every time.
py-phone-caller is a production-ready emergency alert and notification platform that orchestrates voice calls and SMS with Python microservices, Asterisk PBX, and a cloud-native toolchain.
Architecture overview
An alert flow that never drops the signal
py-phone-caller is built as an event-driven, independently deployable microservice mesh. Triggers enter through a webhook, UI, or API, then fan out to a call pipeline that handles generation, playback, and escalation.
Trigger and schedule
Prometheus Alertmanager, the dashboard, or a REST call pushes a notification. The scheduler and Celery worker handle future execution with Redis-backed tasks.
Call orchestration
The Asterisk caller places outbound calls, resolves on-call contacts, and plays generated audio through ARI channels.
Live monitoring
WebSocket listeners monitor call lifecycles, request text-to-speech audio on demand, and log outcomes in the call registry.
Retry and escalation
Failed or unacknowledged calls are retried automatically, escalating to backup contacts while SMS flows keep people informed.
Microservice lineup
11 services, one coordinated response
Each service is independently deployable, Docker-ready, and wired through REST APIs and asynchronous queues.
asterisk_caller
Outbound call orchestrator that queues, places, and plays audio via Asterisk ARI.
asterisk_recaller
Retry engine that enforces windows, backoff, and escalation to backup contacts.
asterisk_ws_monitor
Real-time ARI WebSocket listener for lifecycle events and playback triggers.
caller_register
Call registry that stores attempts, acknowledgements, and message payloads.
generate_audio
Text-to-speech engine supporting gTTS, MMS, Piper, AWS Polly, and Kokoro.
caller_scheduler
Celery-driven scheduler for future calls with Redis-backed task queues.
caller_address_book
Contact and on-call rotation management, including CSV import and export.
caller_sms
SMS gateway with Twilio support and an on-premise USB modem backend.
caller_prometheus_webhook
Alertmanager-compatible webhook that fans alerts into calls and SMS flows.
py_phone_caller_ui
Flask dashboard for calls, schedules, users, and WebSocket event logs.
celery_worker
Background task processor that executes queued and scheduled call jobs.
py-phone-caller-utils
Shared library with Dynaconf settings, Piccolo ORM models, and telemetry hooks.
Capabilities
Built for urgent moments
Every layer is tuned for delivery speed, reliability, and operational visibility.
Web UI tour
See dashboards, schedules, call history, and live event logs in a guided walkthrough.
Open the tourAlert-first delivery
Call-only, SMS-only, SMS-before-call, or parallel call-and-SMS workflows.
Multi-engine voice
Generate audio with multiple cloud or offline TTS engines and cache outputs.
On-call intelligence
Contact routing, rotations, and escalation paths keep teams in the loop.
Observability ready
Telemetry hooks and event logging keep the full call lifecycle visible.
Deployment choice
Run via Docker Compose, systemd services, or full Ansible deployment.
Secure defaults
Dynaconf configuration and secrets management keep credentials out of Git.
Stack
Modern infrastructure, pragmatic choices
Python 3.12, Asterisk 18/20, Redis, PostgreSQL, and Celery anchor the runtime.
Ports
Service endpoints at a glance
Each service exposes a focused API. Only the needed ports should be exposed in production.
| Service | Port | Purpose |
|---|---|---|
| asterisk_caller | 8081 | Place calls |
| generate_audio | 8082 | Generate TTS audio |
| caller_register | 8083 | Store call status |
| caller_prometheus_webhook | 8084 | Alertmanager webhook |
| caller_sms | 8085 | SMS gateway |
| caller_scheduler | 8086 | Schedule calls |
| caller_address_book | 8087 | Contact management |
| py_phone_caller_ui | 5000 | Web dashboard |
Deploy
From local runs to production stacks
Configure once with Dynaconf and ship in the model that fits your environment.
Configuration
Set configuration directories or point to a specific settings file.
export CALLER_CONFIG_DIR=src/config
# OR
export CALLER_CONFIG=/path/to/settings.tomlDocker Compose
Bring up the full stack with containers and service definitions.
cd assets/docker-compose
docker compose up -dGet started
Local run example
Each service can run standalone with a shared configuration and PYTHONPATH.
export CALLER_CONFIG_DIR=src/config
export PYTHONPATH="src:$PYTHONPATH"
python3 -m asterisk_caller.asterisk_caller