pingwa + Home Assistant

Your smart home already knows when the doorbell rings, the alarm trips, or the nightly backup fails. Give it a WhatsApp voice with one rest_command — works with plain YAML you already know, or grab the native integration for a one-click install.

In configuration.yaml, wire an outbound notify to POST /v1/notify. Get an API key by texting join to pingwa on WhatsApp (see home), then store it in secrets.yaml.

# configuration.yaml
rest_command:
  pingwa_notify:
    url: "https://pingwa.dev/v1/notify"
    method: POST
    headers:
      Authorization: !secret pingwa_bearer
      Content-Type: application/json
    payload: '{"text": {{ message | tojson }} }'

# secrets.yaml
pingwa_bearer: "Bearer pw_your_key_here"

The same pattern works for POST /v1/ask, which sends a question and waits for you to tap a button on WhatsApp — handy for anything you want to confirm rather than just be told about. The real request body is {"text": ..., "buttons": [...]} (a plain list of up to 3 short strings; omit buttons for a free-text reply instead).

The server holds the connection open for up to 90 seconds waiting for your reply, then returns 408 — so give the rest_command a matching timeout (HA's default is only 10s and would cut it off). A late reply isn't lost: it's still retrievable from the inbox/reply endpoints below.

# configuration.yaml — add pingwa_ask under the SAME rest_command:
# block as pingwa_notify (one rest_command: key holds all commands)
  pingwa_ask:
    url: "https://pingwa.dev/v1/ask"
    method: POST
    timeout: 95
    headers:
      Authorization: !secret pingwa_bearer
      Content-Type: application/json
    payload: '{"text": {{ message | tojson }}, "buttons": ["Yes", "No"]}'

Three common triggers, all under one automation: key (or drop the list items into automations.yaml if that's how you split your config). The alarm example shows the flagship two-way move: capture the reply with response_variable and branch on which button was tapped. rest_command hands back the HTTP response as {status, content}, so the parsed JSON body lives under .content. Reply buttons get stable ids in order — b0 is the first button ("Yes"), b1 the second ("No") — read at reply.content.reply.button_id.

# configuration.yaml
automation:
  # Doorbell pressed — one-way notify
  - alias: "Doorbell -> WhatsApp"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door_doorbell
        to: "on"
    action:
      - service: rest_command.pingwa_notify
        data:
          message: "Someone's at the front door 🔔"

  # Alarm triggered — ask, then act on the answer
  - alias: "Alarm triggered -> ask on WhatsApp"
    trigger:
      - platform: state
        entity_id: alarm_control_panel.home
        to: "triggered"
    action:
      - service: rest_command.pingwa_ask
        data:
          message: "🚨 Alarm triggered at home. Call the keyholder?"
        response_variable: reply
      # reply.content.reply.button_id is "b0" for "Yes", "b1" for "No"
      # (on a 408 timeout reply.status is 408 — falls to the default branch)
      - choose:
          - conditions: "{{ reply.content.reply.button_id == 'b0' }}"
            sequence:
              - service: script.call_keyholder
        default:
          - service: rest_command.pingwa_notify
            data:
              message: "No 'Yes' tap — not calling the keyholder."

  # Nightly backup failed — one-way notify
  - alias: "Backup failed -> WhatsApp"
    trigger:
      - platform: state
        entity_id: sensor.backup_status
        to: "failed"
    action:
      - service: rest_command.pingwa_notify
        data:
          message: "Nightly backup FAILED — check the logs"

Prefer entities and services over hand-rolled YAML? The pingwa-hass integration wires everything up for you. Install it via HACS as a custom repository (github.com/grzgrzgrz3/pingwa-hass), add your API key, and you get:

pingwa sends through the official Meta WhatsApp Cloud API on its own number, so wiring it into your home automation can't get your personal WhatsApp banned. That is a real distinction from two other kinds of tools people wire into Home Assistant today:

• Unofficial WhatsApp-Web bridges that link your own device by QR scan (the technique behind libraries like Baileys) — fast to set up, but they reverse-engineer WhatsApp's client protocol, violate its terms, and put your personal number at real risk of a permanent ban. See the full comparison.
• One-way webhook-only notifiers — great for a single alert, but they have no concept of a reply, so they can't turn "alarm triggered" into a tap-to-confirm question.

The free plan covers 30 paid-route notifications a month (replies inside your 24h WhatsApp window are free and unlimited). That's not built for streaming every state change in your house — it's built for the handful of things actually worth a phone buzz: someone's at the door, the alarm tripped, the backup failed. Keep high-frequency sensor chatter in HA's own logbook/notifications, and reserve pingwa for the low-volume, high-value pings.

Not affiliated with Home Assistant or the Home Assistant Foundation. rest_command is a standard Home Assistant integration; see their own docs for the full option set. pingwa is an independent, self-hosted service. See about and privacy.