---
title: "Create a channel"
method: POST
path: "/v1/channels"
tags: ["Alerts"]
---

# Create a channel

`POST /v1/channels`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/channels`
- Auth: HTTP bearer

## Request body

- union
  - CreateSlackChannel
    - `kind` 'slack', required
    - `channelId` string, required: A Slack channel id from the connected workspace.
    - `channelName` string, required: The channel name, for the label.
    - `events` string[]: Attention events to receive here, on top of whatever rules send. Omit for none.
  - CreateEmailChannel
    - `kind` 'email', required
    - `emails` string[], required: Each address gets a confirmation link; workspace members are confirmed on sight.
    - `events` string[]: Attention events to receive here, on top of whatever rules send. Omit for none.
  - CreateWebhookChannel
    - `kind` 'webhook', required
    - `url` string, uri, required: Where the signed POSTs go. https in production.
    - `label` string: A name for the channel; the host of the URL when omitted.
    - `headers` object: Extra request headers to send, for your own auth.
    - `events` string[]: Account events to receive at this endpoint (keyword and wallet state changes, attention events), on top of whatever rules send here. Omit for none.

## Response `201`

The created channel. A webhook includes its signing secret, shown only here.

- union
  - SlackChannel
    - `id` string, required: Channel id (dest_...).
    - `label` string, required
    - `stats` object, required: Computed over this workspace's deliveries.
      - `alerts` integer, required: Alerts sending to this channel.
      - `activeAlerts` integer, required: Of those, enabled ones; 0 means the channel receives nothing right now.
      - `lastDeliveryAt` string, nullable, required: Newest delivery attempt, successful or not.
      - `last7d` object, required: Deliveries in the last 7 days.
        - `total` integer, required
        - `failed` integer, required
    - `createdAt` string, required: ISO 8601 timestamp, UTC.
    - `kind` 'slack', required
    - `config` object, required
      - `channelId` string, required: Slack channel id.
      - `channelName` string, required: Slack channel name, without the #.
      - `events` string[], required: The attention events this channel receives on its own, no rule involved: one short message when an item opens (GET /v1/attention). Empty when it receives none.
  - EmailChannel
    - `id` string, required: Channel id (dest_...).
    - `label` string, required
    - `stats` object, required: Computed over this workspace's deliveries.
      - `alerts` integer, required: Alerts sending to this channel.
      - `activeAlerts` integer, required: Of those, enabled ones; 0 means the channel receives nothing right now.
      - `lastDeliveryAt` string, nullable, required: Newest delivery attempt, successful or not.
      - `last7d` object, required: Deliveries in the last 7 days.
        - `total` integer, required
        - `failed` integer, required
    - `createdAt` string, required: ISO 8601 timestamp, UTC.
    - `kind` 'email', required
    - `config` object, required
      - `recipients` object[], required: Every address on the list and whether it confirmed.
        - `email` string, required
        - `confirmedAt` string, nullable, required: Null until the address confirmed through its link; unconfirmed addresses receive nothing.
      - `events` string[], required: The attention events this channel receives on its own, no rule involved: one short message when an item opens (GET /v1/attention). Empty when it receives none.
  - WebhookChannel
    - `id` string, required: Channel id (dest_...).
    - `label` string, required
    - `stats` object, required: Computed over this workspace's deliveries.
      - `alerts` integer, required: Alerts sending to this channel.
      - `activeAlerts` integer, required: Of those, enabled ones; 0 means the channel receives nothing right now.
      - `lastDeliveryAt` string, nullable, required: Newest delivery attempt, successful or not.
      - `last7d` object, required: Deliveries in the last 7 days.
        - `total` integer, required
        - `failed` integer, required
    - `createdAt` string, required: ISO 8601 timestamp, UTC.
    - `kind` 'webhook', required
    - `config` object, required
      - `url` string, required: Where the signed POSTs go.
      - `headers` object, required: Extra request headers you configured.
      - `events` string[], required: The account events this endpoint receives on its own, no rule involved: keyword and wallet state changes and the attention events. Empty when it receives none; mention and digest deliveries come through rules as before.
      - `secret` string: Only on creation and rotation. Signs every request: X-Mentions-Signature-V2 is v2= plus the hex HMAC-SHA256 of "<X-Mentions-Timestamp>.<raw body>" (reject a timestamp older than a few minutes); X-Mentions-Signature, the hex HMAC-SHA256 of the raw body alone, stays for older verifiers.
  - TelegramChannel
    - `id` string, required: Channel id (dest_...).
    - `label` string, required
    - `stats` object, required: Computed over this workspace's deliveries.
      - `alerts` integer, required: Alerts sending to this channel.
      - `activeAlerts` integer, required: Of those, enabled ones; 0 means the channel receives nothing right now.
      - `lastDeliveryAt` string, nullable, required: Newest delivery attempt, successful or not.
      - `last7d` object, required: Deliveries in the last 7 days.
        - `total` integer, required
        - `failed` integer, required
    - `createdAt` string, required: ISO 8601 timestamp, UTC.
    - `kind` 'telegram', required
    - `config` object, required
      - `chatId` string, required: Telegram chat id.
      - `chatType` 'private' | 'group' | 'supergroup' | 'channel', required
      - `events` string[], required: The attention events this channel receives on its own, no rule involved: one short message when an item opens (GET /v1/attention). Empty when it receives none.

## Other responses

- `400`: An event this kind of channel cannot receive: Slack, email and Telegram take the attention events only
- `401`: Missing or invalid API key
- `409`: Slack is not connected for this org

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)