`messaging`

evcc supports the transmission of status information via Telegram, PushOver, ntfy, and many other services using the shoutrrr system. The configuration allows defining custom messages for specific events and systems.

messaging defines in sub-elements what and how to send. The events for which messages should be sent must be defined under events and the services through which the messages should be sent must be defined under services.

For example:

messaging:
  events: ...
  services: ...

`events`

events defines the message content for various predefined events.

The available events are:

start: Charging has started
stop: Charging has stopped
connect: Vehicle connected
disconnect: Vehicle disconnected
soc: Vehicle battery state of charge changed
guest: Unknown vehicle detected

For example:

start: # charge start event
  title: Charge started
  msg: Started charging in "${mode}" mode

`title`

title defines the text for the message title.

For example:

title: Charge started

`msg`

msg defines the text for the message content. Various variables in the format ${<variable name>} can be used to display evcc information in the text.

note

When using variables, make sure to use the correct capitalisation (uppercase/lowercase)!

Useful messages for use in evcc notifications:

msg Variable	Description
`${chargedEnergy:%.1fk}`	Energy amount charged in kWh
`${chargeDuration}`	Charging duration
`${connectedDuration}`	Charger connection duration
`${loadpoint}`	Number of `loadpoints` (charging point) 1,2...
`${mode}`	Active charging mode (see `mode` of `loadpoints`)
`${pvPower:%.1fk}`	Currently measured PV power in kW
`${title}`	Charging point: Text from `loadpoints` `title` parameter
`${vehicleTitle}`	Vehicle: Text from `vehicles` `title` parameter

For example:

  # Message examples using evcc variables
  # start
  msg: Charger ${title} started charging ${vehicleTitle} in ${mode} mode
  # stop
  msg: Charger ${title} finished charging ${vehicleTitle} with ${chargedEnergy:%.1fk}kWh in ${chargeDuration}
  # connect
  msg: ${vehicleTitle} connected on Charger ${title} at ${pvPower:%.1fk}kW PV
  # disconnect
  msg: ${vehicleTitle} disconnected of Charger ${title} after ${connectedDuration}

note

To render the msg texts, you can also use the go text/template syntax in combination with sprig functions.

# Message config using evcc go-text-template rendering, evcc variables and sprig-functions
messaging:
  events:
    start: # charge start event
      title: Charge of {{.vehicleTitle}} started
      msg: |
        Charger {{.title}} started charging {{.vehicleTitle}} in {{ toString .mode | upper }} mode.
        --------------------------
        evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
        Grid power: {{round (divf .gridPower 1000) 3 }} kW
        Solar power: {{round (divf .pvPower 1000) 3 }} kW
        Home consumption: {{round (divf .homePower 1000) 3 }} kW
        {{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
    stop: # charge stop event
      title: Charge of {{.vehicleTitle}} finished
      msg: |
        Charger {{.title}} finished charging {{.vehicleTitle}} 
        with {{round (divf .chargedEnergy 1000) 2 }} kWh in {{.chargeDuration}}.
        --------------------------
        evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
        Grid power: {{round (divf .gridPower 1000) 3 }} kW
        Solar power: {{round (divf .pvPower 1000) 3 }} kW
        Home consumption: {{round (divf .homePower 1000) 3 }} kW
        {{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
    connect: # vehicle connect event
      title: "{{.vehicleTitle}} connected on Charger {{.title}}"
      msg: |
        {{.vehicleTitle}} connected on Charger {{.title}} at {{round (divf .pvPower 1000) 2 }} kW PV.
        --------------------------
        evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
        Grid power: {{round (divf .gridPower 1000) 3 }} kW
        Solar power: {{round (divf .pvPower 1000) 3 }} kW
        Home consumption: {{round (divf .homePower 1000) 3 }} kW
        {{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
    disconnect: # vehicle connected event
      title: "{{.vehicleTitle}} disconnected of Charger {{.title}}"
      msg: |
        {{.vehicleTitle}} disconnected of Charger {{.title}} after {{.connectedDuration}}.
        --------------------------
        evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
        Grid power: {{round (divf .gridPower 1000) 3 }} kW
        Solar power: {{round (divf .pvPower 1000) 3 }} kW


        Home consumption: {{round (divf .homePower 1000) 3 }} kW
        {{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}

List of all evcc-provided variables:

The variables provided by evcc (also see /api/state) must be defined as ${<VariableName>} or in the go-template format {{<VariableName>}} in the message text. Multiple variables in the message text are possible.

Site
- Configuration
  - siteTitle - Main headline of the evcc app (string)
  - prioritySoc - Minimum Powerwall state of charge in percent before PV mode release (integer)
- Information
  - batteryConfigured - Indicator, home battery/Powerwall meter configured (bool)
  - gridConfigured - Indicator, smart/grid meter configured (bool)
  - pvConfigured - Indicator, solar panels/photovoltaic meter configured (bool)
Tariff Information
- currency - Tariff currency (string)
- tariffFeedIn - PV feed-in remuneration per kWh in tariff currency (float)
- tariffGrid - Grid consumption price per kWh in tariff currency (float)
Meter Information
- batteryPower - Current home battery/Powerwall power in watts (float)
- batterySoc - Current state of charge of home battery/Powerwall in percent (integer)
- gridPower - Current grid feed-in(-) or consumption(+) in watts (float)
- homePower - Current home consumption power (excluding Charger consumption) in watts (float)
- pvPower - Current solar panels power in watts (float)
Charging Point (loadpoint)
- Configuration
  - loadpoint - Loadpoint index (integer)
  - maxCurrent - Maximum charging current in amperes (float)
  - minCurrent - Minimum charging current in amperes (float)
  - mode - Initial mode of the charging point after evcc start off/now/min/pv (string)
  - phases - Initial active number of phases of the charging point after evcc start (integer)
  - title - Label of the charging point in the evcc app (string)
- Information
  - activePhases- Currently active number of phases of the charging point (integer)
  - chargeCurrent - Current total charging current in amperes (float)
  - chargeCurrents - Current charging current per active phase in amperes (float)
  - chargeDuration - Charging duration in nanoseconds (integer)
  - chargePower - Current charging power in watts (float)
  - chargeRemainingDuration - Charging time in nanoseconds until the target state of charge (integer)
  - chargeRemainingEnergy - Required energy until the target state of charge in watt-hours (float)
  - chargedEnergy - Energy charged so far in watt-hours (float)
  - charging - Indicator, charging process active (bool)
  - enabled - Indicator, charging enabled (bool)
  - hasVehicle - Indicator, vehicle definitions assigned to the charging point (bool)
  - targetTime - Target charging time in nanoseconds since 1970 UTC (integer)
  - pvAction - Control variable for PV timer control enable/disable (string)
  - pvRemaining - Required PV remaining charging time with activated timer control in nanoseconds (integer)
Vehicles (vehicles)
- Configuration
  - vehicleName - Name/id of the vehicle (string)
  - vehicleTitle - Label of the vehicle in the evcc app (string)
  - vehicleCapacity- Capacity of the vehicle battery in watt-hours (float)
- Information
  - climater - Status of vehicle climatisation on/off/heating/cooling (string)
  - connected - Indicator, vehicle connected to the charging point (bool)
  - connectedDuration - Duration of vehicle connection in nanoseconds (integer)
  - vehicleOdometer - Current vehicle odometer reading in kilometers (float)
  - vehiclePresent - Indicator, evcc can access vehicle data (bool)
  - vehicleRange - Current vehicle range in kilometers (float)
  - vehicleSoc - Current state of charge of the vehicle battery in percent (integer)
Savings Efficiency Information
- savingsAmount - Sum of evcc savings (float)
- savingsEffectivePrice - Calculated savings price (float)
- savingsGridCharged - Consumed grid energy in Wh (float)
- savingsSelfConsumptionCharged - Consumed solar energy in Wh (float)
- savingsSelfConsumptionPercent - Percentage of consumed solar energy in Wh (float)
- savingsSince - Time period of savings calculation in nanoseconds (integer)
- savingsTotalCharged - Total energy consumed in Wh (float)
Charging Session Information
- sessionSolarPercentage - Solar percentage of the session
- sessionPrice - Price of the charged energy of the session
- sessionPricePerKWh - Average price of energy per kWh of the session
- sessionCO<sub>2</sub>PerKWh - Average CO₂ emissions per kWh
Sponsor
- Configuration
  - auth - Authentication token of the evcc sponsor (string)
- Information
  - sponsor - Name of the evcc sponsor (string)

`services`

services defines a list of message services to be used.

For example:

services:
  - type: pushover
    app: 12345
    recipients:
      - 234567

The following sections will now explain all the required parameters.

`type`

type defines the type of message service to be used.

Possible values:

pushover: Pushover. See pushover definition
telegram: Telegram Messenger. See telegram definition
email: Email. See email definition
shout: shoutrrr. See shout definition
ntfy: ntfy. See ntfy definition
custom: Allows the usage of any plugin that supports write access. See custom definition.

Supported Services

`pushover`

pushover uses the Pushover service. Details can be found at Pushover API.

For example:

- type: pushover
  app: # API Token/Key of the created application in Pushover
  recipients:
    -  # List of recipients: either User Key or Delivery Group. Groups created in Pushover can be limited to specific devices.
  devices:
    - Johns phone
    - Mias ticker

`telegram`

telegram uses the Telegram Messenger service.

For example:

- type: telegram
  token: # bot id : each running instance of evcc needs its own bot id
  chats:
    -  # List of chat or group IDs. Each entry requires a - sign in the beginning and must be in a separate line.
    - -GroupID #Note: Group IDs in Telegram have a - sign
    - ChatID

`email`

email uses the shoutrrr service.

Here, the parameter uri with the value smtp://<user>:<password>@<host>:<port>/?fromAddress=<from>&toAddresses=<to> is expected. The placeholders are to be replaced as follows:

<host>: Address (hostname or IP address) of the email server
<port>: Port address of the email server
<user>: Username for the email server
<password>: User password
<from>: Sender's email address
<to>: Recipient's email address

For example:

- type: email
  uri: smtp://username:password@emailserver.domain:1234/?fromAddress=sender@mail.com&toAddresses=recipient@mail.com

`shout`

shout uses the shoutrrr service and supports all its services.

The configuration is shown in the following example using Gotify, and the same applies to the other options through the same method.

For example:

- type: shout
  uri: gotify://gotify.example.com:443/AzyoeNS.D4iJLVa/?priority=1

Further information can be found in the shoutrrr documentation on supported services.

`ntfy`

ntfy uses the ntfy service.

Here, the parameter uri with the value https://<host>/<topics> is expected. The placeholders are to be replaced as follows:

<host>: Address (hostname or IP address) of the ntfy server
<topics>: Subscribed topic or topics

Optional parameters are priority and tags. All parameters are passed as strings.

For example:

- type: ntfy
  uri: https://ntfy.sh/evcctestalerts
  priority: default
  tags: electric_plug,blue_car

Further information can be found in the ntfy documentation.

`custom`

The custom type allows the use of any plugin to process messages. The plugin must support write mode. The message itself is provided in the plugin configuration using the parameter ${send} (or as a template parameter {{.send}}).

Possible Values:

send: Defines the plugin to be used with the source field and plugin-specific parameters. See the example below.
encoding: Specifies the format in which the value for ${send} is provided. The possible values are:
- json: The value is provided as a JSON object in the format { "msg": msg, "title": title }. The title field is only added if it is defined in the events section.
- csv: The fields title and msg are provided as a comma-separated list (title, msg).
- tsv: Similar to csv, but with tab separators.
- title: Only the title (title) is provided.
If encoding is not defined, the msg value is used directly without the title. In this case, only the message defined in msg is used in ${send}.

Example:

messaging:
  events:
    connect:
      title: "Evcc: ${vehicleName} has connected"
      msg: "${vehicleTitle} was connected (Charging mode: ${mode})."
  services:
    - type: custom
      encoding: json
      send:
        # Plugin type
        source: script
        # Plugin-specific configuration.
        # {{.send}} contains the JSON message
        cmd: /usr/local/bin/evcc_message "{{.send}}"

In this example, a shell script (cmd) is invoked with the argument {"title": "...", "msg": "...."}.

events​

title​

msg​

services​

type​

Supported Services​

pushover​

telegram​

email​

shout​

ntfy​

custom​

`events`

`title`

`msg`

`services`

`type`

Supported Services

`pushover`

`telegram`

`email`

`shout`

`ntfy`

`custom`