--- title: "Create a channel" method: POST path: "/channels" tags: ["Channels"] --- # Create a channel `POST /channels` ## Request - Base URL: `https://api.spectate.net/v1` - URL: `https://api.spectate.net/v1/channels` - Auth: HTTP bearer Send `type` and the settings object of that type, for example `type: "email"` with `email: {address}`. Webhook URLs must be public addresses. Slack channels post through a Slack workspace connected under Integrations in the dashboard, Telegram channels are connected there too. Create channels before the escalation paths that use them. ## Request body - CreateChannel: A new notification channel: a name, a type, and the settings object of that type (`email` for `email`, `slack` for `slack`…). Send only that one object. Telegram channels are connected from the dashboard. - `name` string, required: Name shown in escalation paths - `type` 'email' | 'slack' | 'discord' | 'microsoft_teams' | 'telegram' | 'webhook' | 'pushover' | 'sms' | 'voice', required - `enabled` boolean: Whether it delivers from the start. Default `true` - `email` ChannelEmail: Where an `email` channel sends. - `address` string, email, required: The address alerts go to - `slack` ChannelSlackInput: Where a `slack` channel posts. Connect the Slack workspace under Integrations in the dashboard first; `GET /slack-installation` returns the installation's ID. - `installation_id` string, uuid, required: The team's Slack installation (workspace) that posts, from `GET /slack-installation` - `channel` string, required: The Slack channel ID (not its name); invite the Spectate app to private channels - `channel_name` string, nullable: The channel's name, for display - `discord` ChannelWebhookUrlInput: The incoming webhook a `discord` or `microsoft_teams` channel posts to. It's a secret: it's never returned. - `webhook_url` string, uri, required: The incoming webhook URL from Discord (Server settings → Integrations → Webhooks) or a Teams workflow. Must be a public HTTPS address - `microsoft_teams` ChannelWebhookUrlInput: The incoming webhook a `discord` or `microsoft_teams` channel posts to. It's a secret: it's never returned. - `webhook_url` string, uri, required: The incoming webhook URL from Discord (Server settings → Integrations → Webhooks) or a Teams workflow. Must be a public HTTPS address - `webhook` ChannelWebhookInput: Where a `webhook` channel posts its JSON. The URL and header values are write-only. - `url` string, uri, required: The URL to `POST` to; must be a public HTTP or HTTPS address - `headers` ChannelWebhookHeader[]: Headers to send with every request, for example for authentication - `key` string, required: Header name. Hop-by-hop and connection headers are refused - `value` string, required: Header value; write-only, never returned - `pushover` ChannelPushoverInput: Who a `pushover` channel notifies, and with which Pushover application. - `user_key` string, required: The Pushover user or group key - `api_token` string, required: Your Pushover application's API token. Write-only: never returned - `priority` integer: Pushover priority, -2 (lowest) to 2 (emergency). Default 0 - `sms` ChannelPhone: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits. - `phone_number` string, required: The phone number in international format - `voice` ChannelPhone: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits. - `phone_number` string, required: The phone number in international format ## Response `201` The new channel. - Channel: A notification channel: where escalation paths send alerts. The settings of its type are in the object of that name (`email`, `slack`…); the others are `null`. Secrets (webhook URLs, tokens, header values) are never returned. - `id` string, uuid, required: Channel ID - `name` string, required: Name shown in escalation paths - `type` 'email' | 'slack' | 'discord' | 'microsoft_teams' | 'telegram' | 'webhook' | 'pushover' | 'sms' | 'voice', required - `enabled` boolean, required: Whether the channel delivers. `false` when a member turned it off or Spectate did after repeated failures (`auto_disabled`) - `auto_disabled` boolean, required: Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with `enable` - `disabled_at` string, date-time, nullable, required: When the channel was turned off automatically - `disabled_reason` string, nullable, required: Why it was turned off automatically - `consecutive_failures` integer, required: Failed deliveries since the last successful one - `failing_since` string, date-time, nullable, required: Since when deliveries fail - `last_failure_at` string, date-time, nullable, required: When a delivery last failed - `last_failure_reason` string, nullable, required: Why the last delivery failed - `last_delivered_at` string, date-time, nullable, required: When a delivery last succeeded - `email` ChannelEmail, required: Where an `email` channel sends. - `address` string, email, required: The address alerts go to - `slack` ChannelSlack, required: Where a `slack` channel posts: a channel of a Slack workspace connected under Integrations. - `installation_id` string, uuid, nullable, required: The team's Slack installation (workspace) that posts. `null` for older channels with their own bot token - `channel` string, required: The Slack channel ID - `channel_name` string, nullable, required: The channel's name, for display - `telegram` ChannelTelegram, required: The chat a `telegram` channel sends to. Telegram channels are connected from the dashboard (Alerting → Channels), not through the API. - `chat_id` string, required: The Telegram chat ID - `chat_title` string, nullable, required: The chat's title, for display - `webhook` ChannelWebhook, required: What a `webhook` channel sends. The URL and header values can hold credentials, so only the host and the header names are returned. - `host` string, nullable, required: The host of the URL the channel posts to - `header_names` string[], required: Names of the headers it sends - `pushover` ChannelPushover, required: Who a `pushover` channel notifies. The application token is write-only. - `user_key` string, required: The Pushover user or group key - `priority` integer, nullable, required: Pushover priority, -2 (lowest) to 2 (emergency); `null` for normal (0) - `sms` ChannelPhone, required: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits. - `phone_number` string, required: The phone number in international format - `voice` ChannelPhone, required: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits. - `phone_number` string, required: The phone number in international format - `created_at` string, date-time, required: When the channel was created ## Other responses - `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired. - `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team. - `422`: `VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields. - `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`. --- [API](https://skmtc.dev/spectate/apis/spectate-api.md) - [All operations](https://skmtc.dev/spectate/apis/spectate-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spectate/apis/spectate-api/revisions/9b1a233997de?raw)