my_voice_assistant_v3_jamulix/emergency_bridge/README.md

# Notruf-Bridge (seven.io)

Kleiner Webhook-Empfänger, der das Notruf-Payload des Voice Assistants über
[seven.io](https://www.seven.io) in **SMS** und/oder **Sprachanruf (Text-to-Speech)**
umsetzt. Die App bleibt damit provider-agnostisch — der konkrete Anbieter steckt
allein hier.

```
App  --POST /notruf (JSON)-->  Bridge  --seven.io-API-->  📱 SMS  /  ☎️ Anruf
```

## Endpunkte

| Methode | Pfad | Zweck |
|---------|------|-------|
| `GET`  | `/health` | Liveness + ob ein API-Key gesetzt ist |
| `POST` | `/notruf` | nimmt das App-Payload entgegen, löst SMS/Anruf aus |

Erwartetes Payload (von der App erzeugt):

```json
{
  "channels": ["sms", "call"],
  "phones": ["+4915112345678"],
  "message": { "sms": "NOTRUF: …", "call": "Achtung. …" }
}
```

Pro Telefonnummer wird — je nach `channels` — eine SMS (`message.sms`) und/oder ein
Anruf mit vorgelesenem Text (`message.call`, als SSML mit `SEVENIO_VOICE_NAME`)
ausgelöst. Antwort: `{"received": true, "any_sent": <bool>, "results": [...]}`.

## Installation

**Voraussetzung** — die Library [`seven-send`](https://kitux.de/forgejo/dschlueter/seven_send)
muss in der venv installiert sein (sie kapselt die seven.io-Aufrufe):
```bash
sudo -u voice /opt/voice-assistant/.venv/bin/pip install \
     git+https://kitux.de/forgejo/dschlueter/seven_send.git
```

1. **Konfig anlegen:**
   ```bash
   sudo cp emergency_bridge/emergency-bridge.env.example /etc/voice-assistant/emergency-bridge.env
   sudo chown voice:voice /etc/voice-assistant/emergency-bridge.env
   sudo chmod 600 /etc/voice-assistant/emergency-bridge.env
   sudo editor /etc/voice-assistant/emergency-bridge.env   # API-Key + BRIDGE_TOKEN setzen
   ```
2. **Service installieren:**
   ```bash
   sudo cp emergency_bridge/emergency-bridge.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now emergency-bridge
   curl -s localhost:8090/health   # -> {"status":"ok","configured":true}
   ```
3. **App verdrahten** — in `/etc/voice-assistant/voice-assistant.env`:
   ```bash
   EMERGENCY_WEBHOOK_URL=http://127.0.0.1:8090/notruf
   EMERGENCY_WEBHOOK_TOKEN=<derselbe Wert wie BRIDGE_TOKEN>
   EMERGENCY_CONTACT_PHONE=+49XXXXXXXXXX
   ```
   Danach `sudo systemctl restart voice-assistant`.

## Konfiguration (Env)

| Variable | Default | Bedeutung |
|----------|---------|-----------|
| `SEVENIO_API_KEY` | (leer) | seven.io API-Key — ohne Key kein Versand |
| `SEVENIO_SMS_FROM` | `Notruf` | Absender-ID der SMS (alphanumerisch, max. 11 Zeichen) |
| `SEVENIO_VOICE_FROM` | (leer) | Caller-ID des Anrufs (verifizierte Nummer; optional) |
| `SEVENIO_VOICE_NAME` | `de-de-female` | SSML-Stimme für die Anruf-Ansage |
| `BRIDGE_TOKEN` | (leer) | falls gesetzt: `Authorization: Bearer <token>` Pflicht |
| `BRIDGE_HOST` / `BRIDGE_PORT` | `127.0.0.1` / `8090` | Bind-Adresse |

## Test

```bash
.venv/bin/python -m pytest tests/test_emergency_bridge.py -q
```