(pushover-setup)=
# Configuration
For regular usage, configuration is optional, but recommended.
If skipped, each call to the Pushover API needs to specify the required parameters.

## Basic
All functions default required parameters to values specified in the `pushover` namespace in the Salt configuration.
The namespace can either be specified as a mapping key or as a prefix, so both of the following variants are equivalent (with values from the first taking precedence):

```yaml
# e.g. /etc/salt/(minion|master).d/pushover.conf

pushover.token: abAHuZyCLtdH8P4zhmFZmgUHUsv1ei8
pushover.user: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
```

```yaml
# e.g. /etc/salt/(minion|master).d/pushover.conf

pushover:
  token: abAHuZyCLtdH8P4zhmFZmgUHUsv1ei8
  user: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
```

### `token`
The Pushover API token to use for authentication.

### `user`
The user/group ID (key) to send the message to (not the name/email address).

## Returner
The returner module respects more defaults.

```yaml
pushover:
    user: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
    token: azGDORePK8gMaC0QOYAMyEEuzJnyUi
    title: Salt Returner
    device: phone
    priority: -1
    expire: 3600
    retry: 5
```

You can additionally override values in the default `pushover` namespace by specifying an override with a prefix:

```yaml
alternative.pushover:
    priority: 1
    expire: 4800
    retry: 2
```

Request the returner to use the alternative namespace by passing `--return_config alternative` to the Salt command.
Any values not found in the alternative configuration will be pulled from the default namespace.

You can define an arbitrary namespace and merge it into a regular one by specifying `profile` in the latter:

```yaml
pushover_profile:
    pushover.token: azGDORePK8gMaC0QOYAMyEEuzJnyUi

pushover:
    user: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
    profile: pushover_profile

alternative.pushover:
    user: gznej3rKEVAvPUxu9vvNnqpmZpokzF
    profile: pushover_profile
```

### `device`
The name of the device to send the message to.

### `priority`
The priority of the message (integers between `-2` and `2`).

```{note}
  Emergency priority (`2`) requires `expire` and `retry` parameters
  to be set.
```

### `title`
The message title to use.

### `expire`
Stop notifying the user after the specified amount of seconds.
The message is still shown after expiry.

### `retry`
Repeat the notification after this amount of seconds. Minimum: `30`.

### `sound`
The [notification sound](https://pushover.net/api#sounds) to play.