ha-sip-notifier/sip-notifier/README.md

SIP Voice Notifier Add-on

Complete Home Assistant add-on for sending voice notifications via SIP phone calls.

Everything included — just install the add-on, no separate integration needed!

Features

• 📞 Place SIP calls from Home Assistant
• 🔊 Play audio from HTTP/HTTPS URLs (MP3, WAV, etc.)
• 🗣️ Text-to-speech support
• ⚡ One-step installation (add-on includes integration)
• 🔧 Configurable call duration
• 🐳 Container-persistent (survives restarts)

Installation

Method 1: Local Add-on (Development)

1. Copy add-on folder:

   cp -r addon-sip-notifier-v2 /addons/local/sip-notifier
   

2. Add local repository:

   • Settings → Add-ons → Add-on Store → ⋮ (menu) → Repositories
   • Add: file:///addons/local

3. Install from store:

   • Find "SIP Voice Notifier" in local add-ons
   • Click Install

Method 2: GitHub Repository (Production)

1. Create GitHub repo with structure:

   ha-sip-notifier/
   ├── repository.yaml
   └── sip-notifier/
       ├── config.yaml
       ├── Dockerfile
       ├── services.yaml
       └── ...
   

2. Add repository to Home Assistant:

   • Settings → Add-ons → Add-on Store → ⋮ → Repositories
   • Add your GitHub URL

3. Install from store

Configuration

Settings → Add-ons → SIP Voice Notifier → Configuration

Twilio Example

sip_server: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pstn.twilio.com"
sip_user: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
sip_password: "your_auth_token"
default_duration: 30

VoIP.ms Example

sip_server: "yourserver.voip.ms"
sip_user: "123456_subaccount"
sip_password: "your_password"
default_duration: 30

Generic SIP Provider

sip_server: "sip.example.com"
sip_user: "username"
sip_password: "password"
default_duration: 30

Usage

Once the add-on is running, the service sip_notifier.send_notification is automatically available in Home Assistant!

Play Audio from URL

service: sip_notifier.send_notification
data:
  destination: "+15551234567"
  audio_url: "https://example.com/alert.mp3"
  duration: 30

Text-to-Speech

service: sip_notifier.send_notification
data:
  destination: "+15551234567"
  message: "This is a voice notification from Home Assistant"
  duration: 20

Service Parameters

Parameter	Required	Description
destination	Yes	Phone number (+1...) or SIP URI
audio_url	No*	HTTP(S) URL to audio file
message	No*	Text message for TTS
duration	No	Call duration in seconds (default: 30)

* Either audio_url or message required

Example Automations

Water Leak Emergency

automation:
  - alias: "Water Leak Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.water_leak
        to: "on"
    action:
      - service: sip_notifier.send_notification
        data:
          destination: "+15551234567"
          message: "EMERGENCY! Water leak detected!"
          duration: 40

Doorbell Notification

automation:
  - alias: "Doorbell Call"
    trigger:
      - platform: state
        entity_id: binary_sensor.doorbell
        to: "on"
    action:
      - service: sip_notifier.send_notification
        data:
          destination: "+15551234567"
          audio_url: "https://yourdomain.com/doorbell.mp3"
          duration: 15

Motion Detection (Armed Only)

automation:
  - alias: "Security Motion Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.motion
        to: "on"
    condition:
      - condition: state
        entity_id: alarm_control_panel.home
        state: "armed_away"
    action:
      - service: sip_notifier.send_notification
        data:
          destination: "+15551234567"
          message: "Motion detected in your home!"
          duration: 25

How It Works

1. Add-on runs in dedicated container with PJSIP, ffmpeg, etc.
2. Supervisor auto-registers sip_notifier.send_notification service
3. Service call triggers add-on endpoint
4. Add-on downloads/converts audio and places SIP call
5. No separate integration needed!

Troubleshooting

Add-on won't start

Check logs: Settings → Add-ons → SIP Voice Notifier → Log

Common issues:

• Invalid SIP credentials
• SIP server unreachable
• Configuration missing required fields

Service not available

• Ensure add-on is running
• Restart Home Assistant
• Check add-on has homeassistant_api: true in config

Call fails

• Check add-on logs for detailed SIP errors
• Verify phone number format (+15551234567)
• Test SIP credentials with your provider
• Ensure firewall allows UDP port 5060

No audio

• Check audio URL is publicly accessible
• Test with TTS first (message: instead of audio_url:)
• Look for conversion errors in add-on logs
• Ensure audio format is compatible (MP3/WAV recommended)

Audio Format Support

• Input: MP3, WAV, OGG, FLAC, etc. (via pydub)
• Output: Automatically converted to 8kHz mono WAV
• Best performance: Use 8-16kHz mono WAV to skip conversion

SIP Provider Recommendations

Provider	Cost/min	Quality	Setup
Twilio	$0.013	Excellent	Easy
VoIP.ms	$0.009	Very Good	Easy
Vonage	Varies	Good	Medium
Bandwidth	$0.006	Good	Medium

Security

• Add-on runs in isolated container
• SIP credentials stored in encrypted HA config
• API only accessible within Home Assistant network
• No external dependencies besides SIP provider

Performance

• Startup: 2-5 seconds
• Call setup: 3-5 seconds
• Memory: 50-80 MB
• CPU: Low (spike during audio conversion)

Supported Architectures

• aarch64 (Raspberry Pi 3/4/5, 64-bit)
• amd64 (Intel/AMD 64-bit)
• armhf (Raspberry Pi 2/3, 32-bit)
• armv7 (ARM 32-bit)
• i386 (Intel/AMD 32-bit)

What's Different from v1?

v1: Add-on + separate custom integration
v2: Add-on only (integration built-in)

Simpler installation — just one component!

License

MIT

Support

Check add-on logs first: Settings → Add-ons → SIP Voice Notifier → Log

Enable debug logging by restarting the add-on with "Show in sidebar" enabled.