---
title: "Connect a Discord channel"
method: POST
path: "/auth/discord/webhook"
tags: ["Connections"]
---

# Connect a Discord channel

`POST /auth/discord/webhook`

## Request

- Base URL: `https://api.shortsync.app/v1`
- URL: `https://api.shortsync.app/v1/auth/discord/webhook`
- Auth: HTTP bearer

Adds a Discord channel to the workspace by its webhook URL. In
Discord, open Server Settings → Integrations → Webhooks, pick the
channel, and use Copy Webhook URL.

Works for every channel type, including forum channels, which the
dashboard's "Add a channel with Discord" screen can't list. In a
forum channel each post becomes a new forum post titled with
`platform_options.discord.thread_name` (or the caption's first
line), and `first_comment` is its first reply. In text channels
`first_comment` is a separate message right after the post.

The URL is checked against Discord and stored encrypted; it is never
returned. A workspace has one Discord connection that can hold
several channels: each call with a new webhook adds a channel and
returns the same connection `id`; posting a webhook that's already
connected refreshes that channel. The first channel becomes a
default channel; later ones are added with `is_default: false`
(change it with `PATCH /api/v1/discord/channels/{channel_id}`).

## Request body

- object
  - `webhook_url` string, uri, required
  - `label` string: Display name for the channel. Defaults to the webhook's name.

## Response `200`

The workspace's Discord connection, plus the channel that was
added in `channel`.

- object
  - `id` string, required
  - `workspace_id` string, required
  - `platform` 'instagram' | 'tiktok' | 'youtube' | 'facebook' | 'snapchat' | 'pinterest' | 'threads' | 'twitter' | 'bluesky' | 'linkedin' | 'reddit' | 'telegram' | 'mastodon' | 'discord' | 'tumblr' | 'pixelfed' | 'google_business', required
  - `display_name` string, nullable: Username or page name from the upstream platform.
  - `status` 'active' | 'token_expired' | 'refresh_failed' | 'needs_reconnect' | 'rate_limited', required
  - `scopes` string[]: OAuth scopes granted by the user.
  - `connected_at` string, date-time, required
  - `channel` DiscordChannel, required: A Discord channel connected to the workspace. Never includes the webhook URL.
    - `id` string, uuid, required: Pass in `platform_options.discord.channel_ids`.
    - `label` string, required: Display name shown in ShortSync.
    - `guild_id` string, nullable: Discord server id.
    - `guild_name` string, nullable
    - `channel_id` string, required: Discord's channel id.
    - `is_default` boolean, required: Posts without `channel_ids` go to every default channel.
    - `is_forum` boolean, required: Forum channel; each post needs a `thread_name` (falls back to the caption's first line). Learned on the first publish.
    - `status` 'active' | 'needs_reconnect', required: `needs_reconnect` means Discord no longer accepts the webhook.
    - `source` 'paste' | 'oauth', required: Connected by pasting a webhook URL or through Discord sign-in.
    - `created_at` string, date-time, required

## Other responses

- `400`: Missing or malformed webhook URL (`MISSING_WEBHOOK_URL`, `INVALID_WEBHOOK_URL`), the webhook no longer exists (`WEBHOOK_NOT_FOUND`), it isn't a regular incoming webhook (`UNSUPPORTED_WEBHOOK_TYPE`), or Discord couldn't be reached (`WEBHOOK_LOOKUP_FAILED`).
- `401`: Missing, malformed, or revoked token.
- `403`: Token is valid but cannot access this resource. Common cases: - `INSUFFICIENT_SCOPE` - token lacks the required scope. - `WORKSPACE_NOT_ALLOWED` - account token is allowlisted to other workspaces.
- `429`: Per-key sliding-window rate limit (60 req/min), per-org monthly request quota, or per-user upload cap was hit. `RATE_LIMIT_EXCEEDED` carries the window headers; `QUOTA_EXCEEDED` carries `details.quota` (which counter), `used`, `limit`, `resets_at`, and `upgrade_url`. `UPLOAD_QUOTA_EXCEEDED` (Free tier on `POST /posts` only) carries the same shape plus `details.remaining`.

---

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