Discord event handler

Discord is a popular chat service targeted primarily at gamers and by teams outside of gaming looking for a free solution. To configure Kapacitor to send alert messages to Discord, set the applicable configuration options.


Configuration as well as default option values for the Discord event handler are set in your kapacitor.conf. Below is an example configuration:

  enabled = false
  default = true
  url = ""
  workspace = "guild-channel"
  timestamp = true
  username = "Kapacitor"
  avatar-url = ""
  embed-title = "Kapacitor Alert"
  global = false
  state-changes-only = false
  ssl-ca = "/path/to/ca.crt"
  ssl-cert = "/path/to/cert.crt"
  ssl-key = "/path/to/private-key.key"
  insecure-skip-verify = false

Multiple Discord clients may be configured by repeating [[discord]] sections. The workspace acts as a unique identifier for each configured Discord client.


Set to true to enable the Discord event handler.


If multiple Discord client configurations are specified, identify one configuration as the default.


The Discord workspace ID. Set this string to identify this particular Discord configuration. For example, the name of the Discord channel and the guild it’s a part of, such as <guild>-<channel>.


Boolean signifying whether the timestamp should be shown in the embed.


The Discord webhook URL. This can be obtained by adding a webhook in the channel settings - see Intro to Webhooks for a full guide. Discord will provide you with the webhook URL.


Set the Discord bot username to override the username set when generating the webhook.


Set a URL to a specified avatar to override the avatar set when generating the webhook.


Set the title to display in the alert embed. If blank, no title will is set.


Set to true to send all alerts to Discord without explicitly specifying Discord in the TICKscript.


Sets all alerts in state-changes-only mode, meaning alerts will only be sent if the alert state changes. Only applies if global is true.


Set path to certificate authority file.


Set path to host certificate file.


Set path to certificate private key file.


Set to true to use SSL but skip chain and host verification. This is necessary if using a self-signed certificate.


Set the following Discord event handler options in a handler file or when using .discord() in a TICKscript.

workspacestringSpecifies which Discord configuration to use when there are multiple.
timestampboolSpecifies whether to show the timestamp in the embed footer. If blank uses the choice from the configuration.
usernamestringUsername of the Discord bot. If empty uses the username from the configuration.
avatar-urlstringURL of image to use as the webhook’s avatar. If empty uses the url from the configuration.
embed-titlestringTitle of alert embed posted to the webhook. If empty uses the title set in the configuration.

Example: handler file

id: handler-id
topic: topic-name
kind: discord
  workspace: 'guild-channel'
  username: 'Kapacitor'
  avatar-url: ''
  timestamp: true
  embed-title: 'Kapacitor Alert'

Example: TICKscript

  // ...
    .embedTitle('Kapacitor Alert')

Set up Guild

To allow Kapacitor to send alerts to Discord, obtain a webhook url from Discord - see Intro to Webhooks Then, add the generated webhook URL as the url in the [[discord]] configuration section of your kapacitor.conf.

Using the Discord event handler

With one or more Discord event handlers enabled and configured in your kapacitor.conf, use the .discord() attribute in your TICKscripts to send alerts to Discord or define a Discord handler that subscribes to a topic and sends published alerts to Discord.

To avoid posting a message every alert interval, use AlertNode.StateChangesOnly so only events where the alert changed state are sent to Discord.

See examples below for sample Discord configurations defined the kapacitor.conf:

Discord settings in kapacitor.conf

  enabled = true
  default = true
  url = ""
  workspace = "guild-alerts"
  timestamp = true
  username = "AlertBot"
  avatar-url = ""
  embed-title = "Alert"
  global = false
  state-changes-only = false

  enabled = true
  default = false
  url = ""
  workspace = "guild-errors"
  timestamp = true
  username = "StatsBot"
  avatar-url = ""
  embed-title = "Errors"
  global = false
  state-changes-only = false

Send alerts to Discord from a TICKscript

Use the .discord() event handler in your TICKscript to send an alert. For example, this configuration will send an alert with the message “Hey, check your CPU”, to the Discord channel whenever idle CPU usage drops below 20%.


    .warn(lambda: "usage_idle" < 20)
    .message('Hey, check your CPU')
      .embedTitle('Uh Oh!')  

Send alerts to Discord from a defined handler

Add a Discord handler that subscribes to the cpu by creating a TICKscript that publishes alert messages to a topic. For example, this configuration will send an alert with the message “Hey, check your CPU”. A Discord handler is added that subscribes to the cpu topic and publishes all alert messages to Discord.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an critical alert message to the cpu topic any time idle CPU usage drops below 5%.


    .crit(lambda: "usage_idle" < 5)
    .message('Hey, check your CPU')

Add and enable the TICKscript:

kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert

Create a handler file that subscribes to the cpu topic and uses the Discord event handler to send alerts to Discord. This handler is using the non-default Discord handler, “critical-alerts”, which sends messages to the #critical-alerts channel in Discord.


id: discord-cpu-alert
topic: cpu
kind: discord
  workspace: 'guild-alerts'
  embed-title: 'Hey, Listen!'

Add the handler:

kapacitor define-topic-handler discord_cpu_handler.yaml

Using multiple Discord configurations

Kapacitor can use multiple Discord integrations, each identified by the value of the workspace config. The TICKscript below illustrates how multiple Discord integrations can be used.

In the kapacitor.conf above, there are two Discord configurations; one for alerts and the other for daily stats. The workspace configuration for each Discord configuration act as a unique identifiers.

The following TICKscript sends alerts to the alerts Discord workspace.


    .crit(lambda: "usage_idle" < 5)
    .message('Hey, I think the machine is on fire.')

Error rates are also stored in the same InfluxDB instance and we want to send daily reports of 500 errors to the error-reports Discord workspace. The following TICKscript collects 500 error occurrences and publishes them to the 500-errors topic.


    .info(lamda: 'count' > 0)

Below is an aggregate handler that subscribes to the 500-errors topic, aggregates the number of 500 errors over a 24 hour period, then publishes an aggregate message to the 500-errors-24h topic.


id: 500-errors-24h
topic: 500-errors
kind: aggregate
  interval: 24h
  topic: 500-errors-24h
  message: '{{ .Count }} 500 errors last 24 hours.'

Last, but not least, a Discord handler that subscribes to the 500-errors-24h topic and publishes aggregated count messages to the error-reports Discord workspace:


id: discord-500-errors-daily
topic: 500-errors-24h
kind: discord
  workspace: guild-errors

Was this page helpful?

Thank you for your feedback!

Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

State of the InfluxDB Cloud Serverless documentation

InfluxDB Cloud Serverless documentation is a work in progress.

The new documentation for InfluxDB Cloud Serverless is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.