# Discord

Send, edit, pin and react to messages from your Discord bot or a channel webhook, and manage channels, members, roles, timeouts and bans.

## Connect Discord

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `discord` and choose **Discord**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Bot Token · Optional**: The token of your app’s bot (not a client secret and not a user token). Every operation but Webhook › Send Message needs it.
- **Webhook URL · Optional**: Channel settings → Integrations → Webhooks → Copy Webhook URL. Used by Webhook › Send Message when the step names none. Anyone with it can post in the channel.

Paste your Discord app’s bot token: Developer Portal → your app → Bot → Reset Token. Invite the bot to your server with OAuth2 → URL Generator (scope bot, plus the permissions it needs). Reading members needs the Server Members intent (Bot → Privileged Gateway Intents). To only send messages to one channel without a bot, paste that channel’s webhook URL instead.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in Discord

Add a **Discord** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Message](https://docs.gorunner.io/apps/discord#fields-f-message): Send · Send and Wait for Approval · Get · Get Many · Edit · React With Emoji · Pin · Unpin · Delete
- [Channel](https://docs.gorunner.io/apps/discord#fields-f-channel): Create · Get · Get Many · Update · Delete
- [Member](https://docs.gorunner.io/apps/discord#fields-f-member): Get · Get Many · Add Role · Remove Role · Timeout · Kick · Ban · Unban
- [Role](https://docs.gorunner.io/apps/discord#fields-f-role): Get Many · Create · Update · Delete
- [Webhook](https://docs.gorunner.io/apps/discord#fields-f-webhook): Send Message

To start a workflow from Discord, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Discord can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Discord says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Discord is `pieceId: "discord"` with `actionId: "discord"`, set by `resource` and an `operation_…` field, such as `operation_channel`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Discord › Message

### Send

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Send To · Optional**: A channel, or a person as a direct message. Options: Channel, User (direct message). Default: Channel.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **User ID · Required**: The person to message. They must share a server with the bot and allow direct messages from it. Shows when **Send To** is **User (direct message)**.
- **Message · Optional**: The text, up to 2,000 characters (Markdown works). A message needs text, an embed or a file.
- **Embeds · Optional**: Up to 10 rich embeds, such as [{"title": "Order #1042", "description": "Shipped to Berlin", "color": 5793266, "url": "https://shop.example.com/o/1042"}].
- **Components · Optional**: Buttons or menus under the message, as Discord defines them, such as [{"type": 1, "components": [{"type": 2, "style": 5, "label": "Open order", "url": "https://shop.example.com/o/1042"}]}].
- **Files · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Up to 10 files, 20 MB each.
- **Reply To Message · Optional**: Send as a reply to this message (its ID or link) in the same channel.
- **No Link Previews · Optional**: Don't show previews of the links in the message. Off by default.
- **Send Silently · Optional**: Deliver without push or desktop notifications. Off by default.
- **Allow @everyone and @here · Optional**: Let @everyone and @here in the text notify. Off, they show as text: data from an earlier step can never ping the whole server. Off by default.
- **Read Aloud (TTS) · Optional**: Read the message aloud to people viewing the channel (needs Send TTS Messages). Off by default.

### Send and Wait for Approval

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Send To · Optional**: A channel, or a person as a direct message. Options: Channel, User (direct message). Default: Channel.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **User ID · Required**: The person to message. They must share a server with the bot and allow direct messages from it. Shows when **Send To** is **User (direct message)**.
- **Message · Required**: What the person is asked to decide. Its first line is the title the run page shows.
- **Buttons · Optional**: Approve and Reject, or a single Approve button when the only useful answer is yes. Options: Approve and Reject, Approve only. Default: Approve and Reject.
- **Approve Button Label · Optional**: Default: Approve.
- **Reject Button Label · Optional**: Default: Reject. Shows when **Buttons** isn’t **Approve only**.
- **Auto-continue after (timeout) · Optional**: Resume automatically after this long if nobody answers (0 = wait indefinitely). Then status is "timed_out": branch on status == "approved". Default: 0.
- **Timeout Unit · Optional**: Options: Seconds, Minutes, Hours, Days. Default: Hours.
- **Public Base URL · Optional**: This installation's public address, for the buttons' links. Defaults to PUBLIC_API_URL. It must open for the person deciding: a link on localhost is one nobody can answer.
- **Reply To Message · Optional**: Send as a reply to this message (its ID or link) in the same channel.
- **No Link Previews · Optional**: Don't show previews of the links in the message. Off by default.
- **Send Silently · Optional**: Deliver without push or desktop notifications. Off by default.
- **Allow @everyone and @here · Optional**: Let @everyone and @here in the text notify. Off, they show as text: data from an earlier step can never ping the whole server. Off by default.

### Get

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **Message ID · Required**: The message's ID or link (right-click the message → Copy Message Link).

### Get Many

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **Return All · Optional**: Read every message, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–2000). Default: 50. Shows when **Return All** is off.

### Edit

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **Message ID · Required**: The message's ID or link (right-click the message → Copy Message Link).
- **Message · Optional**: The text, up to 2,000 characters (Markdown works). A message needs text, an embed or a file.
- **Embeds · Optional**: Up to 10 rich embeds, such as [{"title": "Order #1042", "description": "Shipped to Berlin", "color": 5793266, "url": "https://shop.example.com/o/1042"}].
- **Components · Optional**: Buttons or menus under the message, as Discord defines them, such as [{"type": 1, "components": [{"type": 2, "style": 5, "label": "Open order", "url": "https://shop.example.com/o/1042"}]}].

### React With Emoji

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **Message ID · Required**: The message's ID or link (right-click the message → Copy Message Link).
- **Emoji · Required**: A Unicode emoji (👍), or a custom one as name:id.

### Pin, Unpin and Delete

- **Server · Optional**: The server whose channels the Channel list shows. Not sent to Discord.
- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link. Shows when **Send To** isn’t **User (direct message)**.
- **Message ID · Required**: The message's ID or link (right-click the message → Copy Message Link).
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Discord › Channel

### Create

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Name · Required**: 1 to 100 characters. Discord lowercases text channel names and turns spaces into dashes.
- **Type · Optional**: Options: Text, Voice, Category, Announcement, Stage, Forum, Media. Default: Text.
- **Topic · Optional**: Up to 1,024 characters (4,096 for forums).
- **Category ID · Optional**: Put the channel in this category.
- **Position · Optional**
- **Age-Restricted · Optional**
- **Slow Mode (seconds) · Optional**: How long each person waits between messages (0 to 21,600).
- **Bitrate · Optional**: Voice and stage channels: bits per second (8,000 to 96,000; more on boosted servers).
- **User Limit · Optional**: Voice channels: how many people may join (0 = no limit).
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Get

- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link.

### Get Many

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Return All · Optional**: Read every channel, page by page (at most 500; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many channels to return (1–500). Default: 100. Shows when **Return All** is off.

### Update

- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link.
- **New Name · Optional**
- **Topic · Optional**: Up to 1,024 characters (4,096 for forums).
- **Category ID · Optional**: Put the channel in this category.
- **Position · Optional**
- **Age-Restricted · Optional**
- **Slow Mode (seconds) · Optional**: How long each person waits between messages (0 to 21,600).
- **Bitrate · Optional**: Voice and stage channels: bits per second (8,000 to 96,000; more on boosted servers).
- **User Limit · Optional**: Voice channels: how many people may join (0 = no limit).
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Delete

- **Channel · Required**: The channel (or thread). Pick a server above to list its channels, or paste a channel ID or a message link.
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Discord › Member

### Get

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **User ID · Required**: The person's ID or @mention.

### Get Many

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Return All · Optional**: Read every member, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many members to return (1–5000). Default: 100. Shows when **Return All** is off.

### Add Role and Remove Role

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **User ID · Required**: The person's ID or @mention.
- **Role · Required**: The role to add or remove (several: their IDs separated by commas, or a list from an expression). The bot's own role must sit above them.
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Timeout

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **User ID · Required**: The person's ID or @mention.
- **Timeout Until · Required**: When the person may write again: a date and time up to 28 days ahead (ISO 8601, such as 2026-11-08T18:00:00Z).
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Kick and Unban

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **User ID · Required**: The person's ID or @mention.
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Ban

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **User ID · Required**: The person's ID or @mention.
- **Delete Their Messages From the Last (hours) · Optional**: 0 to 168 (7 days). Default: 0.
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Discord › Role

### Get Many

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Return All · Optional**: Read every role, page by page (at most 250; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many roles to return (1–250). Default: 100. Shows when **Return All** is off.

### Create

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Name · Optional**: Up to 100 characters. Required to create.
- **Color · Optional**: A hex color such as #5865F2.
- **Permissions · Optional**: The permission bit set as a number (Discord's permission calculator gives it). Empty: the server's default.
- **Show Separately · Optional**: List members with this role on their own in the member list.
- **Mentionable · Optional**
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Update

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Role · Required**: The role to change or delete.
- **Name · Optional**: Up to 100 characters. Required to create.
- **Color · Optional**: A hex color such as #5865F2.
- **Permissions · Optional**: The permission bit set as a number (Discord's permission calculator gives it). Empty: the server's default.
- **Show Separately · Optional**: List members with this role on their own in the member list.
- **Mentionable · Optional**
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Delete

- **Server · Required**: The server (guild). Lists the servers the bot is in.
- **Role · Required**: The role to change or delete.
- **Reason · Optional**: Shown in the server's audit log (up to 512 characters).

### Discord › Webhook

### Send Message

- **Webhook URL · Optional**: Channel settings → Integrations → Webhooks → Copy Webhook URL. Empty: the connection's webhook URL. Anyone with it can post in the channel, so it is kept like a password.
- **Message · Optional**: The text, up to 2,000 characters. A message needs text, an embed or a file.
- **Embeds · Optional**: Up to 10 rich embeds, such as [{"title": "Order #1042", "description": "Shipped to Berlin", "color": 5793266, "url": "https://shop.example.com/o/1042"}].
- **Files · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Up to 10 files, 20 MB each.
- **Username · Optional**: Post under this name instead of the webhook's.
- **Avatar URL · Optional**: Post with this picture instead of the webhook's.
- **Thread ID · Optional**: Post into this thread of the webhook's channel.
- **Read Aloud (TTS) · Optional**: Off by default.
- **No Link Previews · Optional**: Don't show previews of the links in the message. Off by default.
- **Send Silently · Optional**: Deliver without push or desktop notifications. Off by default.
- **Allow @everyone and @here · Optional**: Let @everyone and @here in the text notify. Off, they show as text: data from an earlier step can never ping the whole server. Off by default.

Source: https://docs.gorunner.io/apps/discord