SMS gateway for SIM800C USB modems with web UI, REST API, webhooks and Home Assistant add-on
  • Python 76.2%
  • JavaScript 13.4%
  • CSS 5.5%
  • HTML 2.9%
  • Shell 1.4%
  • Other 0.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-08 13:13:23 +01:00
addon Drop 32-bit add-on builds, move add-on base to Python 3.14 / Alpine 3.24, add MIT LICENSE 2026-11-08 13:12:43 +01:00
docs Add monster logo: favicon, header brand, README wordmark 2026-10-31 23:12:28 +01:00
scripts Publish add-on as pre-built image and move its metadata to SMSMonster-addon 2026-10-31 22:33:44 +01:00
src/smsmonster Add Home Assistant integration: sensors for modems and messages, smsmonster_* events 2026-11-01 01:17:09 +01:00
tests Drop 32-bit add-on builds, move add-on base to Python 3.14 / Alpine 3.24, add MIT LICENSE 2026-11-08 13:12:43 +01:00
.dockerignore Publish add-on as pre-built image and move its metadata to SMSMonster-addon 2026-10-31 22:33:44 +01:00
.gitignore Publish add-on as pre-built image and move its metadata to SMSMonster-addon 2026-10-31 22:33:44 +01:00
docker-compose.yml Harden API auth and treat all modem input as untrusted 2026-10-30 00:47:36 +01:00
Dockerfile Initial SMS Monster: SIM800C SMS gateway with web UI, REST API, webhooks and Home Assistant add-on 2026-10-28 00:25:55 +01:00
Dockerfile.dev Initial SMS Monster: SIM800C SMS gateway with web UI, REST API, webhooks and Home Assistant add-on 2026-10-28 00:25:55 +01:00
LICENSE Drop 32-bit add-on builds, move add-on base to Python 3.14 / Alpine 3.24, add MIT LICENSE 2026-11-08 13:12:43 +01:00
pyproject.toml Bump version to 0.3.0 2026-11-08 13:13:23 +01:00
README.md Drop 32-bit add-on builds, move add-on base to Python 3.14 / Alpine 3.24, add MIT LICENSE 2026-11-08 13:12:43 +01:00

SMS Monster

Self-hosted SMS gateway for small in-network setups. Plug one or more SIM800C USB modems into a Raspberry Pi (or any Linux box), run one container, and you get:

  • a web UI to read, send and search SMS across all modems (live updates, no polling)
  • a JSON REST API with optional token auth
  • webhooks for incoming SMS, sent/failed messages, incoming calls and modem status (HMAC signed), or ntfy push notifications
  • full PDU mode: GSM-7 and Unicode (UCS-2), long/concatenated messages in both directions, alphanumeric senders
  • per-modem status: signal, operator, registration, IMEI/ICCID, SIM PIN handling, USSD queries (prepaid balance), raw AT console
  • hot-plug: modems are discovered when connected and reconnected after a power dip; serial ports that are not modems can be ignored from the UI
  • a Home Assistant add-on (Ingress UI, uart access), published from addon/ to a separate add-on repository
  • a built-in Home Assistant integration: modems, counters and the latest messages appear as sensors, every SMS/call fires an HA event (automatic in the add-on, or point any instance at HA with a long-lived token)

Everything is pure Python (no compiled wheels) so it builds on armv7/arm64/amd64 alike.

Screenshots

Taken from the built-in demo (python tests/demo_server.py, two simulated modems, no hardware).

Modems Messages
Modem overview Message list with filters
Send Webhooks
Send form with part counter Webhook management
AT console USSD query
Raw AT console per modem USSD balance query

The UI follows the system colour scheme (light mode) and works on phones (mobile view).

Hardware notes

  • Each SIM800C module needs its own USB-serial converter (most breakouts have a CH340 or CP2102 on board).
  • Power: SIM800 draws up to 2 A in bursts. Use a good 5 V supply / powered hub, otherwise you will see UNDER-VOLTAGE warnings and random reconnects.
  • The SIM800C autobauds on the first AT. SMS Monster probes 115200 first, then 9600 (configurable).
  • Disable the SIM PIN, or set SMSMONSTER_SIM_PIN.

Run with Docker Compose (standalone)

docker compose up -d --build

Open http://<host>:8080. Edit docker-compose.yml to map your modems (/dev/ttyUSB0, …) or use the device_cgroup_rules variant shown there for hot-plug of any USB serial adapter. Data (SQLite) lives in ./data.

Configuration (environment variables)

Variable Default Meaning
SMSMONSTER_DEVICES auto auto = scan /dev/serial/by-id, /dev/ttyUSB*, /dev/ttyACM*; or comma separated paths / pyserial URLs (socket://host:5555, rfc2217://host:port)
SMSMONSTER_BAUDRATES 115200,9600,57600,38400 Baud rates to probe
SMSMONSTER_SIM_PIN PIN to enter when the SIM asks for it
SMSMONSTER_API_TOKEN If set, /api/* needs Authorization: Bearer <token> (or X-API-Key; ?token= only on /api/events). Set it whenever port 8080 is reachable from anything but localhost.
SMSMONSTER_PORT / SMSMONSTER_HOST 8080 / 0.0.0.0 Listen address
SMSMONSTER_DATA_DIR ./data (/data in Docker) SQLite location
SMSMONSTER_LOG_LEVEL info debug logs every AT exchange
SMSMONSTER_HANGUP_CALLS true Log and reject incoming calls
SMSMONSTER_DELIVERY_REPORTS false Request delivery reports (sent → delivered)
SMSMONSTER_DELETE_FROM_SIM true Delete SMS from the SIM after storing them
SMSMONSTER_SEND_RETRIES 3 Attempts before an outgoing SMS is marked failed
SMSMONSTER_STATUS_INTERVAL 30 Seconds between signal/registration polls
SMSMONSTER_SWEEP_INTERVAL 120 Seconds between SIM storage sweeps (catches missed notifications)
SMSMONSTER_PART_TIMEOUT 600 Seconds to wait for missing parts of a long SMS before storing it incomplete
SMSMONSTER_MAX_INCOMING_PER_MIN 120 Per-modem cap on stored incoming SMS/calls per minute; excess stays on the SIM until a later sweep (0 = unlimited)
SMSMONSTER_HA_URL / SMSMONSTER_HA_TOKEN Push modems and messages into a Home Assistant instance at this URL (http://homeassistant.local:8123) using a long-lived access token. The add-on does this automatically through the Supervisor
SMSMONSTER_HA_INTEGRATION true Set to false to turn the Home Assistant integration off (also inside the add-on)
SMSMONSTER_HA_RESYNC_INTERVAL 60 Seconds between full re-pushes of all entities (recovers after a Home Assistant restart)
SMSMONSTER_TRUST_INGRESS false Let requests whose TCP peer is the Home Assistant Supervisor (172.30.32.2) bypass the API token. The add-on sets this; leave it off elsewhere

Modem on another machine (or Docker Desktop)

Docker Desktop runs containers in a VM and cannot pass USB serial devices through. Bridge the port over TCP on the machine that owns the modem and point SMS Monster at it:

socat TCP-LISTEN:5555,bind=127.0.0.1,reuseaddr,fork,max-children=1 /dev/ttyUSB0,b115200,raw,echo=0
SMSMONSTER_DEVICES=socket://host.docker.internal:5555   # or ser2net / rfc2217://host:port

Home Assistant add-on

Add the SMS Monster add-on repository to your Home Assistant

Click the button above, or add the repository by hand: Settings → Apps → App store → ⋮ → Repositories, paste https://github.com/manzari/SMSMonster-addon, then install SMS Monster. Home Assistant calls add-ons "apps" now. It pulls a pre-built image, so no build happens on the device. Images exist for 64-bit systems only (aarch64, amd64), matching what Home Assistant itself still supports.

That repository only holds the add-on metadata (config.yaml, DOCS.md, CHANGELOG.md). The image itself is built from this repository (addon/Dockerfile, addon/run.sh, base images in addon/build.yaml) and pushed to the container registry on git.hauptstadt.monster as manzari/{arch}-smsmonster:<version>.

To release: bump version in pyproject.toml, commit, then run scripts/release-addon.sh "what changed". It builds and pushes one image per architecture (needs docker login git.hauptstadt.monster once and buildx with QEMU for the arm targets), tags this repo v<version>, and commits the version bump plus changelog line to the add-on repository checked out next to this one (../SMSMonster-addon, override with ADDON_REPO). Home Assistant then offers the update on its next store refresh.

Options, rest_command and webhook-trigger examples are in the add-on repository's DOCS.md.

Home Assistant integration

Inside the add-on this is automatic (the Supervisor hands the add-on a token and homeassistant_api: true grants it access to the Core API). Standalone, set SMSMONSTER_HA_URL and SMSMONSTER_HA_TOKEN (Profile → Security → Long-lived access tokens). SMS Monster then keeps these entities up to date through the REST API, re-pushing everything every SMSMONSTER_HA_RESYNC_INTERVAL seconds so they survive a Home Assistant restart:

Entity State Attributes
sensor.sms_monster_modem_<imei> ready, connecting, disconnected, sim_pin_required, … operator, registration, signal, IMEI/ICCID/IMSI, model, firmware, name, phone_number, last_error, counters
sensor.sms_monster_modem_<imei>_signal signal strength in % rssi, signal_dbm
sensor.sms_monster_modems number of modems ready count, list of modems
sensor.sms_monster_received / _sent / _failed / _queued message counters
sensor.sms_monster_last_received / _last_sent / _last_failed / _last_call timestamp of the latest one id, number, text, modem_id, status, error

Entities of unplugged or ignored modems are removed. In addition every message fires an event with the full message as event data: smsmonster_message_received, smsmonster_message_sent, smsmonster_message_failed, smsmonster_call_received, smsmonster_modem_removed. Example automation:

triggers:
  - trigger: event
    event_type: smsmonster_message_received
actions:
  - action: notify.mobile_app_phone
    data:
      title: "SMS from {{ trigger.event.data.number }}"
      message: "{{ trigger.event.data.text }}"

Sending still goes through the REST API (rest_command, see the add-on DOCS.md); the HA REST API cannot register services.

Security notes

  • The API token is the only access boundary. Anyone holding it has full modem control: the AT console can dial numbers, change the SIM PIN or reset the modem, and the message list exposes every SMS (2FA codes included).
  • Without a token the API is open to everyone who can reach the port; a warning is logged at start-up.
  • POST/PATCH bodies must be sent with Content-Type: application/json (this also blocks cross-site form posts).
  • Everything the modem sends is treated as untrusted input: lines and responses are size-capped, identity strings are sanitised, incoming traffic is rate limited per modem and a misbehaving modem is disconnected, never trusted.
  • socket:// / rfc2217:// modems are plain TCP. Only bridge over a network you trust; an attacker on that path is an evil modem.
  • Webhook URLs are called from inside the container (use this to reach Home Assistant, but it also means any internal URL is reachable for whoever manages webhooks). Webhook secrets are stored in plain text in the SQLite file.

REST API

All endpoints return JSON. With a token configured send Authorization: Bearer <token> and, for bodies, Content-Type: application/json.

Method & path Purpose
GET /api/health Liveness, version, modem counts
GET /api/stats Message counters + modem list
GET /api/modems · GET /api/modems/{id} Modem status (id = IMEI)
PATCH /api/modems/{id} {"name": "...", "phone_number": "..."}
POST /api/modems/{id}/at {"command": "AT+CSQ"} raw AT command
POST /api/modems/{id}/ussd {"code": "*100#"} USSD query
POST /api/modems/{id}/restart Re-open and re-initialise the modem
POST /api/modems/{id}/ignore Close the port and never scan it again (for serial devices that are not modems)
GET /api/ignored · DELETE /api/ignored?device=… List / restore ignored serial devices
POST /api/messages (alias /api/send) {"to": "+4917…", "text": "…", "modem_id": "optional"} → 202 queued message
GET /api/messages Filters: `direction=in
GET/DELETE /api/messages/{id} · POST /api/messages/{id}/retry Single message
GET/POST /api/webhooks · PATCH/DELETE /api/webhooks/{id} · POST …/test Webhook management
GET /api/events Server-Sent Events stream (?token= for auth)

Example:

curl -X POST http://pi:8080/api/messages -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' -d '{"to": "+491701234567", "text": "Hello from the Pi"}'

Message statuses: queued → sending → sent (→ delivered) | failed. Incoming messages are received.

Webhooks

POST with body {"event": "<name>", "data": {...}}, header X-SMSMonster-Event, and if a secret is set X-SMSMonster-Signature: sha256=<hex HMAC of the body>. Events: message.received, message.sent, message.failed, message.updated, call.received, modem.updated, modem.removed, or *. Failed deliveries are retried 3 times.

ntfy

Create a webhook with "type": "ntfy" and the topic URL as url (e.g. https://ntfy.sh/my-sms, or your own server). Each event becomes a push notification with a readable title and the message text; failures and removed modems are sent with high priority. The optional secret is sent as the ntfy access token (tk_...) or, when it contains a colon, as user:password basic auth.

curl -X POST http://pi:8080/api/webhooks -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' \
  -d '{"type": "ntfy", "url": "https://ntfy.sh/my-sms", "events": ["message.received", "message.failed"]}'

Development

Everything runs in Docker; nothing is installed on the host.

docker build -f Dockerfile.dev -t smsmonster:dev .
docker run --rm -v "$PWD":/app smsmonster:dev pytest            # unit + API tests against a simulated SIM800C
docker run --rm -v "$PWD":/app -p 8080:8080 smsmonster:dev python tests/demo_server.py   # UI with two fake modems
docker build --target test .                                    # same tests as a build stage (CI)

Layout: src/smsmonster/pdu.py (PDU codec), modem.py (per-modem worker thread, AT protocol), manager.py (discovery/hot-plug), db.py (SQLite), api.py (Starlette routes + SSE), webhooks.py, static/ (vanilla JS UI, relative URLs so it works behind Ingress). tests/fake_sim800.py simulates a modem.

Roadmap / ideas

  • MQTT publishing for a tighter Home Assistant integration
  • Other modems (SIM7600, Quectel) mostly need different init strings
  • Contacts / conversation view

License

MIT, see LICENSE. Bugs and ideas go to the issue tracker.