Your phone system meets your smart home

Overview

The GonoPBX Home Assistant integration connects your Asterisk PBX to your smart home. You get real-time status of extensions and trunks, call statistics as sensors, and can trigger automations based on call events.

Step 1: Prepare GonoPBX

First, configure an API key and optionally MQTT in your GonoPBX installation. Edit the .env file in the GonoPBX directory:

# API key for Home Assistant
HA_API_KEY=your-secure-api-key-here

# Optional: MQTT for real-time events
MQTT_BROKER=192.168.1.100    # IP of your Mosquitto broker
MQTT_PORT=1883
MQTT_USER=ha_user
MQTT_PASSWORD=ha_password

Then restart GonoPBX:

cd /root/gonopbx
docker compose up -d --build backend

Step 2: Install the HACS integration

Option A: via HACS (recommended)

1. Open HACS in Home Assistant
2. Click the three-dots menu → Custom repositories
3. Enter: https://github.com/ankaios76/gonopbx-homeassistant as an Integration
4. Search for “GonoPBX” and click Install
5. Restart Home Assistant

Option B: manual

1. Download the repository:
   git clone https://github.com/ankaios76/gonopbx-homeassistant.git
2. Copy the folder custom_components/gonopbx/ to
   /config/custom_components/gonopbx/ in your HA installation
3. Restart Home Assistant

Step 3: Configure the integration

1. Go to Settings → Devices & Services → Add Integration
2. Search for GonoPBX
3. Enter the connection details:
   • Host: IP address of your GonoPBX server
   • Port: 8000 (default)
   • API Key: The HA_API_KEY from your .env
   • Enable MQTT: Check if MQTT is configured in GonoPBX

Available entities

Binary sensors (online/offline)

• binary_sensor.gonopbx_system – Overall PBX status
• binary_sensor.gonopbx_ext_1001 – Per-extension status
• binary_sensor.gonopbx_trunk_plusnet – Per-trunk status

Sensors

• sensor.gonopbx_active_calls – Active calls
• sensor.gonopbx_calls_today – Calls today
• sensor.gonopbx_calls_missed – Missed calls
• sensor.gonopbx_voicemail_unread – Unread voicemails

Services

• gonopbx.make_call – Start a call from an extension
• gonopbx.toggle_forwarding – Enable/disable call forwarding

MQTT events

If MQTT is enabled, Home Assistant receives real-time events for every call. You can use these events directly as automation triggers:

• gonopbx_call_started – Call started (includes caller, destination)
• gonopbx_call_answered – Call answered
• gonopbx_call_ended – Call ended (includes duration, disposition)

Automations – examples

# automations.yaml
automation:
  - alias: "Missed call notification"
    trigger:
      - platform: event
        event_type: gonopbx_call_ended
    condition:
      - condition: template
        value_template: >
          {{ trigger.event.data.disposition == 'NO ANSWER' }}
    action:
      - service: notify.mobile_app
        data:
          title: "Missed call"
          message: >
            Call from {{ trigger.event.data.caller }}

automation:
  - alias: "Mute TV on call"
    trigger:
      - platform: event
        event_type: gonopbx_call_started
    action:
      - service: media_player.volume_mute
        target:
          entity_id: media_player.living_room_tv
        data:
          is_volume_muted: true

# In Automations or Developer Tools → Services:
service: gonopbx.make_call
data:
  extension: "1001"
  number: "004930123456"

automation:
  - alias: "Forwarding when away"
    trigger:
      - platform: state
        entity_id: person.me
        to: "not_home"
    action:
      - service: gonopbx.toggle_forwarding
        data:
          forward_id: 1
          enabled: true

MQTT topics (reference)

GonoPBX publishes the following MQTT topics:

Help & Support

If you have questions or issues, open an issue on GitHub:

• HACS integration – Issues
• GonoPBX backend – Issues