# Home Assistant

NoticeFox's field names follow Home Assistant's notification vocabulary, so the built-in
[RESTful notifier](https://www.home-assistant.io/integrations/notify.rest/) maps onto the
JSON endpoint directly. Create a send token labeled "Home Assistant" first; every
notification will show "via Home Assistant".

Keep the token in `secrets.yaml`, never in `configuration.yaml`:

```yaml
# secrets.yaml
noticefox_authorization: "Bearer nfx_send_…"
```

## A notifier

```yaml
# configuration.yaml
notify:
  - name: noticefox
    platform: rest
    resource: https://api.noticefox.app/v1/notifications
    method: POST_JSON
    headers:
      Authorization: !secret noticefox_authorization
    message_param_name: message
    title_param_name: title
    target_param_name: target
```

Use it from an automation or a script:

```yaml
action: notify.noticefox
data:
  title: Washer
  message: The laundry is done
  target: watch
```

`target` is optional (`auto` by default): `iphone`, `watch`, `vision`, or a device name or
id, exactly as spelled. The platform names `ios`, `watchos` and `visionos` are not targets and
reach nothing. Fixed extra fields go under the notifier's own `data:` key, for example
`data: {level: time-sensitive, scene: notice}`; Home Assistant sends them with every
notification from that notifier.

## A scene with parameters: `rest_command`

For per-notification scenes, levels and tags, a
[`rest_command`](https://www.home-assistant.io/integrations/rest_command/) gives full
control of the JSON body:

```yaml
# configuration.yaml
rest_command:
  noticefox_garage:
    url: https://api.noticefox.app/v1/notifications
    method: post
    content_type: application/json
    headers:
      Authorization: !secret noticefox_authorization
    payload: >-
      {"title": "Garage", "message": "Door {{ state }}",
       "scene": "garage", "scene_params": {"doorState": "{{ state }}"},
       "level": "time-sensitive", "tag": "garage-door", "group": "home"}
```

```yaml
# An automation's action
action: rest_command.noticefox_garage
data:
  state: "{{ trigger.to_state.state }}"
```

`doorState` takes `open`, `closed`, `opening` or `closing`, which are the states of Home
Assistant's garage-door covers. The `tag` makes each new door notification replace the last
one on the devices it reaches, so the lock screen shows only the current state. Keep the
`target` the same for every update of one tag: a newer send to only the iPhone leaves the
older one on the Watch.

## Troubleshooting

- `401`: the token is wrong, revoked or expired. Check the `Bearer ` prefix in
  `secrets.yaml`.
- `400 invalid_field`: a field NoticeFox doesn't know; the error's `field` names it.
- `429 rate_limited`: more than 30 sends a minute from this token. Add a condition or a
  delay to the automation.

All codes: [Error codes](errors.md).