5.6

.env.example

@@ -1,10 +1,8 @@
-COMMAND_SOURCE="stdin" # or "mqtt"
-
 PORT="5060"
 LOG_LEVEL="2"
 NAME_SERVER=""
 CACHE_DIR=""
-GLOBAL_OPTIONS=""
+GLOBAL_OPTIONS="--enable-mqtt --mqtt-address 192.168.1.1 --mqtt-port 1883 --mqtt-username admin --mqtt-password password --mqtt-topic=hasip/execute --mqtt-state-topic hasip/state"
 
 SIP1_ENABLED="True"
 SIP1_ID_URI="sip:homeassistant@fritz.box"
@@ -49,10 +47,3 @@ HA_WEBHOOK_ID="sip_call_webhook_id_test"
 
 SENSOR_ENABLED="True"
 SENSOR_ENTITY_PREFIX="ha-sip"
-
-BROKER_ADDRESS=""
-BROKER_PORT="1883"
-BROKER_USERNAME=""
-BROKER_PASSWORD=""
-MQTT_TOPIC="hasip/execute"
-MQTT_STATE_TOPIC="hasip/state"

README.md

@@ -1,6 +1,6 @@
 # ![logo](icon.png) ha-sip 
 
-### Home Assistant SIP/VoIP Gateway is a Home Assistant add-on which 
+### Home Assistant SIP/VoIP Gateway is a Home Assistant app which 
 - allows the dialing and hanging up of phone numbers through a SIP end-point 
 - triggering of services through dial tones (DTMF) after the call was established.
 - listens for incoming calls and can trigger actions through a web-hook (the call is not picked up)
@@ -12,11 +12,11 @@
 
 ## Installation
 
-[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Farnonym%2Fha-plugins)
+[![Open your Home Assistant instance and show the add app repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Farnonym%2Fha-plugins)
 
-This add-on is for the Home Assistant OS or supervised installation methods mentioned in
+This app is for the Home Assistant OS or supervised installation methods mentioned in
 https://www.home-assistant.io/installation/. With that in place you can install this third-party plug-in like described in
-https://www.home-assistant.io/common-tasks/os#installing-a-third-party-add-on-repository. The repository URL is
+https://www.home-assistant.io/common-tasks/os#installing-a-third-party-app-repository. The repository URL is
 `https://github.com/arnonym/ha-plugins`.
 
 > **Note:**
@@ -40,7 +40,7 @@ sip:
     realm: '*'
     user_name: homeassistant
     password: secure
-    answer_mode: listen  # "listen" or "accept", see below
+    answer_mode: listen  # "listen", "accept", or "reject". see below
     settle_time: 1 # time to wait for playing the message/actions/etc. after call was established
     incoming_call_file: "" # config and menu definition file for incoming calls, see below
     options: ''
@@ -70,12 +70,12 @@ webhook:
 
 > **Note** 
 > For TTS you need to install one of the [TTS integrations](https://www.home-assistant.io/integrations/#text-to-speech). 
-> If you're unsure about the entity id used for `engine_id`, set `debug_print` to `true` and restart the add-on.
-> The add-on will output a list of all available engines and languages into the log. If the configured engine and language
+> If you're unsure about the entity id used for `engine_id`, set `debug_print` to `true` and restart the app.
+> The app will output a list of all available engines and languages into the log. If the configured engine and language
 > is valid, it will also log the available voices (if the engine supports it).
 
 > **Note** 
-> You are able to access the /config and /media directory inside the add-on for config files, audio files, cache and recordings. 
+> You are able to access the /config and /media directory inside the app for config files, audio files, cache and recordings. 
 
 #### For `global_options` you can specify the following options
 
@@ -91,6 +91,19 @@ webhook:
   --tls-port TLS_PORT   Port to use for TLS transport (default: 5061)
   --debug-headers {enabled,enable,true,yes,on,1,disabled,disable,false,no,off,0}
                         Enable debug printing of all available SIP headers (default: disabled)
+  --enable-mqtt         Enable MQTT as a command source (default: disabled)
+  --mqtt-address MQTT_ADDRESS
+                        MQTT broker address (default: empty)
+  --mqtt-port MQTT_PORT
+                        MQTT broker port (default: 1883)
+  --mqtt-username MQTT_USERNAME
+                        MQTT broker username (default: empty)
+  --mqtt-password MQTT_PASSWORD
+                        MQTT broker password (default: empty)
+  --mqtt-topic MQTT_TOPIC
+                        MQTT topic to subscribe to for incoming commands (default: hasip/execute)
+  --mqtt-state-topic MQTT_STATE_TOPIC
+                        MQTT topic to publish call state events to (default: hasip/state)
 ```
 
 #### For `options` on each SIP account there are
@@ -121,6 +134,8 @@ webhook:
                         Set the TURN password (default: None)
   --extract-headers EXTRACT_HEADERS
                         Comma-separated list of SIP headers to extract and include in webhooks (default: None)
+  --reject-sip-code REJECT_SIP_CODE
+                        SIP response code used when rejecting incoming calls in reject mode (default: 603)
 ```
 
 ## Usage
@@ -168,6 +183,9 @@ data:
     input:
         command: hangup
         number: sip:**620@fritz.box
+        sip_code: 486 # optional SIP status code (e.g. 486 "Busy Here", 603 "Decline")
+                      # only applied when the call has not been answered yet;
+                      # ignored for already active calls
 ```
 
 #### To send DTMF digits to an established call:
@@ -293,7 +311,7 @@ data:
 In `listen` mode no call will be answered (picked up) but you can trigger an automation through a [Webhook trigger](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger) for every incoming call.
 The webhook ID must match the ID set in the configuration.
 
-You can get the caller from `{{trigger.json.caller}}` or `{{trigger.json.parsed_caller}}` for usage in e.g. the action of your automation. 
+You can get the remote from `{{trigger.json.remote_uri}}` or `{{trigger.json.parsed_remote_uri}}` for usage in e.g. the action of your automation. 
 If you want to react on a webhook message with another command you should use `{{ trigger.json.internal_id }}` as the number.
 If you also use the menu ID webhook you need to check for `{{ trigger.json.event == "incoming_call" }}` e.g. in a "Choose" action type.
 
@@ -302,8 +320,9 @@ Example of "incoming call" webhook message:
 ```json
 {
     "event": "incoming_call",
-    "caller": "<sip:5551234456@fritz.box>",
-    "parsed_caller": "5551234456",
+    "call_direction": "incoming",
+    "remote_uri": "<sip:5551234456@fritz.box>",
+    "parsed_remote_uri": "5551234456",
     "sip_account": 1,
     "internal_id": "something-unique"
 }
@@ -335,7 +354,7 @@ If you don't provide a menu the menu from `incoming_call_file` will be used.
 #### Accept mode
 
 In `accept` mode you can additionally make ha-sip to accept the call. For this you can define a menu per SIP account. Put a config file
-into your `/config` directory of your home-assistant installation (e.g. use the samba add-on to access that directory).
+into your `/config` directory of your home-assistant installation (e.g. use the samba app to access that directory).
 
 Example content of `/config/sip-1-incoming.yaml`:
 
@@ -372,7 +391,16 @@ menu:
             post_action: return
 ```
 
-After that you set `incoming_call_file` in the add-on configuration to `/config/sip-1-incoming.yaml`.
+After that you set `incoming_call_file` in the app configuration to `/config/sip-1-incoming.yaml`.
+
+#### Reject mode
+
+In `reject` mode every incoming call is automatically rejected. No audio is played and the call is never
+answered. A webhook is still triggered for each rejected call, so you can still react to incoming calls
+in your automations (e.g. for logging or notifications).
+
+The SIP response code sent to the caller defaults to `603 Decline` and can be changed via the
+`--reject-sip-code` option on the SIP account (e.g. `--reject-sip-code 486` for "Busy Here").
 
 ## Call menu definition
 
@@ -382,7 +410,7 @@ used for incoming and outgoing calls.
 menu:
     id: main # If "id" is present, a message will be sent via webhook (entered_menu), see below (optional)
     message: Please enter your access code # the message to be played via TTS (optional, defaults to empty)
-    language: en # TTS language (optional, defaults to the global language from add-on config)
+    language: en # TTS language (optional, defaults to the global language from app config)
     choices_are_pin: true # If the choices should be handled like PINs (optional, defaults to false)
     timeout: 10 # time in seconds before "timeout" choice is triggered (optional, defaults to 300)
     post_action: noop # this action will be triggered after the message was played. Can be 
@@ -432,7 +460,7 @@ menu:
 ```
 
 > **Note:** 
-> The audio files need to reside in your home-assistant `config` directory, as this is the only directory accessible inside the add-on.
+> The audio files need to reside in your home-assistant `config` or `media` directory, as these are the only directory accessible inside the app.
 
 ## Web-hooks
 
@@ -444,16 +472,19 @@ These are the common fields available in all webhook events:
 ```json
 {
     "internal_id": "something-unique",
-    "caller": "<sip:5551234456@fritz.box>",
-    "called": "<sip:sip-user@fritz.box>",
-    "parsed_caller": "5551234456",
-    "parsed_called": "sip-user",
+    "call_direction": "incoming",
+    "local_uri": "<sip:sip-user@fritz.box>",
+    "remote_uri": "<sip:5551234456@fritz.box>",
+    "parsed_local_uri": "sip-user",
+    "parsed_remote_uri": "5551234456",
     "sip_account": 1,
     "call_id": "7490FE75C2CB1D45@192.168.178.1",
     "headers": {}
 }
 ```
 
+`call_direction` is either `"incoming"` or `"outgoing"`.
+
 > **Note:** The `headers` field contains extracted SIP headers if `--extract-headers` is configured on the SIP account, 
 > otherwise it's an empty object. See [SIP Header Extraction](#sip-header-extraction) for more details.
 
@@ -570,7 +601,7 @@ ha-sip can expose sensor entities to Home Assistant for monitoring SIP account s
 These only show information regarding ha-sip itself, not the SIP provider (you cannot see calls that are
 answered on other SIP devices, as this is not supported by the SIP protocol).
 
-To enable sensors, add the following to your add-on configuration:
+To enable sensors, add the following to your app configuration:
 
 ```yaml
 sensors:
@@ -587,10 +618,10 @@ Tracks whether a call is currently active on each SIP account.
 | `sensor.{prefix}_account_{n}` | `true` / `false` | Whether a call is active |
 
 **Attributes when active:**
-- `caller`: Full caller URI
-- `called`: Full called URI
-- `parsed_caller`: Extracted caller number
-- `parsed_called`: Extracted called number
+- `remote_uri`: Full remote party URI
+- `local_uri`: Full local SIP account URI
+- `parsed_remote_uri`: Extracted remote party number
+- `parsed_local_uri`: Extracted local SIP account number
 - `sip_account`: Account number
 - `call_id`: SIP call ID
 - `headers`: Extracted SIP headers (if configured)
@@ -623,10 +654,10 @@ Tracks information about the most recent call on each account.
 | `sensor.{prefix}_last_call_{n}` | `incoming` / `outgoing` / `none` | Direction of last call |
 
 **Attributes:**
-- `caller`: Full caller URI
-- `called`: Full called URI
-- `parsed_caller`: Extracted caller number
-- `parsed_called`: Extracted called number
+- `remote_uri`: Full remote party URI
+- `local_uri`: Full local SIP account URI
+- `parsed_remote_uri`: Extracted remote party number
+- `parsed_local_uri`: Extracted local SIP account number
 - `call_id`: SIP call ID
 - `timestamp`: ISO timestamp when call ended
 
@@ -665,7 +696,7 @@ automation:
       - service: logbook.log
         data:
           name: "Incoming Call"
-          message: "Call from {{ state_attr('sensor.ha_sip_last_call_1', 'parsed_caller') }}"
+          message: "Call from {{ state_attr('sensor.ha_sip_last_call_1', 'parsed_remote_uri') }}"
 ```
 
 ## SIP Header Extraction
@@ -687,8 +718,9 @@ The extracted headers will be included in all webhook events for calls on that a
 ```json
 {
     "event": "incoming_call",
-    "caller": "<sip:5551234456@provider.com>",
-    "parsed_caller": "5551234456",
+    "call_direction": "incoming",
+    "remote_uri": "<sip:5551234456@provider.com>",
+    "parsed_remote_uri": "5551234456",
     "sip_account": 1,
     "headers": {
         "X-Caller-ID": "John Doe",
@@ -796,7 +828,7 @@ All the examples are working also for incoming calls when you copy the `menu` pa
 
 ## Troubleshooting
 
-The first place to look is the log of the ha-sip add-on. There you can see individual SIP messages and the logs of
+The first place to look is the log of the ha-sip app. There you can see individual SIP messages and the logs of
 ha-sip itself (prefixed with "|").
 
 ## Stand-alone mode
@@ -806,10 +838,14 @@ Instead of stdin - MQTT will be used for communication.
 
 1. Follow the instructions from home assistant to set up a working MQTT broker and install the MQTT integration [MQTT Broker](https://www.home-assistant.io/integrations/mqtt/)
 2. Copy `.env.example` to `.env` and replace the variable place-holders with your real configuration.
-3. Make sure you switched the `COMMAND_SOURCE` in your .env file from "stdin" to "mqtt" and set the `BROKER_*` variables to connect to your MQTT broker address
+3. In your `.env` file, enable MQTT through `GLOBAL_OPTIONS` and point it at your broker, for example:
+
+   ```
+   GLOBAL_OPTIONS="--enable-mqtt --mqtt-address 192.168.1.1 --mqtt-port 1883 --mqtt-username admin --mqtt-password secret --mqtt-topic hasip/execute --mqtt-state-topic hasip/state"
+   ```
 4. Install [docker compose plugin](https://docs.docker.com/compose/install/linux/#install-using-the-repository)
 5. Run `docker compose up -d` in the main folder of the application to run the ha-sip service
-6. Now you can use the `mqtt.publish` service in home assistant to send commands as json to the `hasip/execute` topic from your automations
+6. Now you can use the `mqtt.publish` service in home assistant to send commands as json to the topic configured in `--mqtt-topic` (defaults to `hasip/execute`) from your automations
 
    Example:
    ```yaml
@@ -820,7 +856,7 @@ Instead of stdin - MQTT will be used for communication.
         topic: hasip/execute
     ```
 
-7. You can listen to call state event on the topic configured in `MQTT_STATE_TOPIC` (defaults to `hasip/state`).
+7. You can listen to call state events on the topic configured in `--mqtt-state-topic` (defaults to `hasip/state`).
 
 ## Support
 
@@ -836,8 +872,8 @@ Your support helps others discover the project and keeps me motivated.
    `HA_BASE_URL` is something like "http://homeassistant.local:8123/api"
 
    The access token is created from http://homeassistant.local:8123/profile
-4. Run `./build.sh run-local` to run the add-on locally
-5. Paste commands as json (without line-breaks) into stdin of the running add-on:
+4. Run `./build.sh run-local` to run the app locally
+5. Paste commands as json (without line-breaks) into stdin of the running app:
 
    Example:
    ```json