Skip to content
Get the appGet app

Switchboard without the integration

The Aivi integration sets up Switchboard and Remote buttons from a panel in Home Assistant, and presses reach Home Assistant over a connection it opens itself, with no webhook, no open port and no Home Assistant Cloud. This page is for wiring it with your own automations instead: one publishes the tiles, and a webhook automation carries out the presses.

Buttons and Toggles explains how a press travels, what a tile shows while it waits, and how an update confirms it. The steps below follow that model.

  • The update_widget RESTful command from the Home Assistant widgets guide. If you haven’t published a widget from Home Assistant yet, that guide sets it up step by step.
  • A widget with the Switchboard template, created in the app with the slug living-room.
  • A public HTTPS address for Home Assistant on port 443, for example a Home Assistant Cloud webhook URL. See Reaching Home Assistant.

The example publishes a switchboard with two scenes and two toggles, and turns presses into service calls.

  1. Publish the switchboard whenever one of its entities changes. Every update carries the whole content, with each toggle’s on read from its entity:

    - alias: "Aivi: publish the living room switchboard"
    triggers:
    - trigger: state
    entity_id:
    - light.porch
    - switch.fountain
    - trigger: homeassistant
    event: start
    actions:
    - action: rest_command.update_widget
    data:
    slug: living-room
    payload: >-
    {{ {"content": {"template": "switchboard", "actions": [
    {"id": "movie", "label": "Movie", "icon": "tv.fill"},
    {"id": "all_off", "label": "All off", "icon": "power"},
    {"id": "porch", "label": "Porch light", "icon": "lightbulb.fill",
    "kind": "toggle", "color": "yellow", "on": is_state("light.porch", "on")},
    {"id": "fountain", "label": "Fountain", "icon": "drop.fill",
    "kind": "toggle", "color": "cyan", "on": is_state("switch.fountain", "on")}
    ]}} | tojson }}

    This automation also confirms a toggle press: turning the porch light on changes its state, and the update fills in the tile. A scene changes none of these entities, so step 3 runs this automation after each scene or script to answer the button press.

  2. Make a token of your own. Aivi sends it with every press, and the automation in the next step checks it, so that only Aivi can use the webhook:

    openssl rand -hex 32
  3. Receive presses with a webhook trigger. It checks the token, drops expired presses, then carries out the action:

    - alias: "Aivi: living room switchboard presses"
    mode: queued
    max: 10
    triggers:
    - trigger: webhook
    webhook_id: "[webhook-id]"
    allowed_methods: [POST]
    local_only: true
    conditions:
    - condition: template
    value_template: "{{ trigger.json.token == '[shared-secret]' }}"
    actions:
    - variables:
    event: "{{ trigger.json.event | from_json }}"
    - condition: template
    value_template: >-
    {{ event.type == 'widget.action.v1'
    and as_timestamp(event.expires_at, 0) > as_timestamp(now()) }}
    - choose:
    - conditions: "{{ event.data.action == 'movie' }}"
    sequence:
    - action: scene.turn_on
    target: { entity_id: scene.movie }
    - action: automation.trigger
    target: { entity_id: automation.aivi_publish_the_living_room_switchboard }
    - conditions: "{{ event.data.action == 'all_off' }}"
    sequence:
    - action: script.turn_on
    target: { entity_id: script.all_off }
    - action: automation.trigger
    target: { entity_id: automation.aivi_publish_the_living_room_switchboard }
    - conditions: "{{ event.data.kind == 'toggle' }}"
    sequence:
    - variables:
    entity: >-
    {{ {"porch": "light.porch", "fountain": "switch.fountain"}[event.data.action] }}
    - if: "{{ event.data.value }}"
    then:
    - action: homeassistant.turn_on
    target: { entity_id: "{{ entity }}" }
    else:
    - action: homeassistant.turn_off
    target: { entity_id: "{{ entity }}" }

    The event’s fields are listed under Event types.

  4. Point the widget’s webhooks at it. The "*" entry catches every action, and the body template carries your token and the whole event:

    curl https://api.getaivi.app/widgets/living-room/webhooks \
    -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Token [token]" \
    -d '{"webhooks": {"*": {"url": "[webhook-url]", "body": {"token": "[shared-secret]", "event": "{{event_json}}"}}}}'

The same recipe drives a Remote widget: publish "template": "remote" content instead. For a Remote Live Activity, publish with a rest_command for PATCH /activities/{slug} with "state": "ONGOING", check for activity.action.v1 in step 3, and set the webhooks on /activities/{slug}/webhooks in step 4.