---
title: Microsoft Teams event handler
list_title: Microsoft Teams
description: >
  The Microsoft Teams event handler lets you send Kapacitor alerts to a Microsoft Teams channel. This page includes configuration options and usage examples.
menu:
  kapacitor_v1:
    name: Microsoft Teams
    weight: 750
    parent: Event handlers
aliases:
  - /kapacitor/v1/event_handlers/microsoftteams/
---

[Microsoft Teams](https://www.microsoft.com/en-us/microsoft-365/microsoft-teams/group-chat-software) is a widely used "digital workspace" that facilitates communication among team members. To configure Kapacitor to send alerts to one or more Microsoft Teams channels, do the following:

- [Set up a Teams](#set-up-teams)
  - [Configuration](#configuration)
  - [Handler file options](#handler-file-options)
  - [Example Teams handler file](#example-handler-file)
- [Example alerts](#example-alerts)
- [Send an alert to Teams](#example-alerts)

## Set up Teams

1. Log in to Teams, and then [create a new incoming webhook](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/connectors#setting-up-a-custom-incoming-webhook) for a Teams channel.
2. In your `kapacitor.conf` file, add a `[teams]` section with [configuration options](#configuration) for the Microsoft Teams event
handler, including the incoming webhook URL as the `channelurl`. For example:

  ```toml
  [teams]
    enabled = true
    default = true
    channel-url =  "https://outlook.office.com/webhook/..."
    global = true
    state-changes-only = true
  ```

3. To add multiple Microsoft Teams clients, repeat steps 1-2 to obtain a new web hook and add another `[teams]` section in `kapacitor.conf`.
The `channelurl` acts as a unique identifier for each configured Teams client.

### Configuration

#### `enabled`

Set to `true` to enable the Microsoft Teams event handler.

#### `default`

If there are multiple `teams` configurations, identify one as the default.

#### `channelurl`

Specify the Microsoft Team webhook URL to send messages and alerts.

#### `global`

Set to true to send all alerts to Teams without explicitly specifying Microsoft Teams in the TICKscript.\

#### `state-changes-only`

Set to true to send alerts for state-changes-only.
_Only applies if `global` is `true`._

### Handler file options

The following options can be set in a Microsoft Teams event [handler file](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file) or when using
`.teams()` in a TICKscript.

| Name       | Type   | Description                                                                               |
| ----       | ----   | -----------                                                                               |
| team       | string | Specifies which Team configuration to use when there are multiple configurations.         |
| channel    | string | Teams channel to post messages to. If empty uses the channel from the configuration.      |

### Example handler file

```yaml
id: handler-id
topic: topic-name
kind: teams
options:
  team: 'teams.microsoft.com/team/'
  channel: '#alerts'
```

For information about using handler files, see [Add and use event handlers](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file).

## Example alerts

#### Send alert to Teams channel in configuration file

```js
  stream
    |alert()
       .teams()
```

#### Send alert to Teams channel with webhook (overrides configuration file)

```js
  stream
    |alert()
       .teams()
       .channelURL('https://outlook.office.com/webhook/...')
```

#### Send alerts to Teams from a TICKscript

Use the `.teams()` attribute in your TICKscripts to:

- Send alerts to Teams
- Define a Teams handler that subscribes to a topic and sends published alerts to Teams

> To avoid posting a message every alert interval, use
> [AlertNode.StateChangesOnly](/kapacitor/v1/reference/nodes/alert_node/#statechangesonly)
> so only events where the alert changed state are sent to Teams.

The following TICKscript uses the `.teams()` event handler to send the message,
"Hey, check your CPU", to the `#alerts` Teams channel when idle CPU usage drops below 20%.

_**teams-cpu-alert.tick**_  
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .warn(lambda: "usage_idle" < 20)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .teams()
```

#### Send alerts to Teams from a defined handler

The following example sends an alert to the `cpu` topic with the message,
"Hey, check your CPU".
A Teams handler is added that subscribes to the `cpu` topic and publishes all
alert messages to Teams.

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%.

_**cpu\_alert.tick**_
```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 5)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .topic('cpu')
```

Add and enable the TICKscript:

```bash
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 Teams
event handler to send alerts to Teams. This handler uses a non-default Teams
handler, "critical-alerts", which sends messages to the #critical-alerts channel
in Teams.

_**teams\_cpu\_handler.yaml**_
```yaml
id: teams-cpu-alert
topic: cpu
kind: teams
channelurl: 'alerts'

```

Add the handler:

```bash
kapacitor define-topic-handler teams_cpu_handler.yaml
```