# Discord for Twenty

Connect Discord to your Twenty workflows. Post messages, edit them, react,
delete, and browse channels — all from the workflow builder or the AI chat.

## What you can do

Once installed and the admin has provided the bot token, five tools become
available in workflows and the AI chat:

- **Send Discord message** — *"post 'New deal closed 🎉' to #general"*. As a
  workflow step: provide `channelId` + `messageText`. Optional
  `replyToMessageId` turns it into a reply to a previous message.
- **Update Discord message** — edit a message the bot already sent. Useful
  for status messages that change as a workflow progresses.
- **Delete Discord message** — remove a bot message (for example after a
  mistake or when a workflow is cancelled).
- **Add Discord reaction** — react with a unicode emoji (`👍`, `✅`, `🎉`)
  or a custom server emoji (`partyparrot:643452342342342342`). Great for
  signalling status at a glance.
- **List Discord channels** — discovers the text-postable channels in a
  Discord server, useful as the first step in a workflow that picks a
  channel dynamically. **Leave `guildId` blank if your bot is in only one
  server — it auto-picks.** If the bot is in multiple servers, the error
  response lists each server's name and ID so you can copy the right one.

## Installing

1. Open **Settings → Applications** in your Twenty workspace.
2. Find **Discord** in the available apps and click **Install**.
3. Use any of the tools above in a workflow step or via the AI chat.

> **Heads up:** if you see *"Discord is not configured"* on the first run,
> your Twenty admin needs to follow the [Self-hosting setup](#self-hosting-setup-admin-only)
> section below — they need to create a Discord application and provide the
> bot token before the tools work.

## Finding channel and message IDs

Discord IDs are long numeric strings (e.g. `1234567890123456789`). To copy
them from the Discord client:

1. **Enable Developer Mode** once: **User Settings → Advanced → Developer
   Mode** (toggle on). Discord then shows extra "Copy ID" options on
   right-click.
2. **Channel ID** — right-click any channel → *Copy Channel ID*.
3. **Message ID** — right-click any message → *Copy Message ID*.
4. **Server (guild) ID** — right-click the server icon → *Copy Server ID*.
   Only needed for `discord-list-channels` when your bot is in multiple
   servers (otherwise leave it blank for auto-pick).

> **Tip:** when chaining steps, pass `messageId` from a previous *Send
> Discord message* step directly into a follow-up *Update / Delete / Add
> Reaction* step. No copy/paste needed.

## Limitations

What this connector intentionally does **not** support in v1:

- **Direct messages to users.** Discord's DM API needs a different identity
  flow.
- **Threads.** Replying inside a thread or starting a new one isn't exposed.
- **Webhooks.** Uses the bot REST API only.
- **Slash commands / interactions.** The bot doesn't register or respond to
  `/commands`.
- **Per-workspace identity.** All Twenty workspaces in the same Twenty
  deployment share the same Discord bot.
- **2000-character message limit.** Discord rejects longer payloads with
  HTTP 400.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Discord is not configured` | `DISCORD_BOT_TOKEN` not set | Admin: paste the bot token in Settings → Applications → Discord → **Settings tab** |
| `401 Unauthorized` | Token wrong, copied with whitespace, or rotated | Reset the token in the Discord Developer Portal and re-paste |
| `Missing Access (50001)` | Bot wasn't invited to that server | Re-run the OAuth invite URL for that server (see admin setup) |
| `Missing Permissions (50013)` | Bot is in the server but lacks Send / Manage / React permissions | In Discord: server settings → roles → grant the bot's role the missing permission |
| `Unknown Channel (10003)` | `channelId` is wrong, or bot can't see that channel | Verify the ID; check the bot has *View Channel* permission |
| `Unknown Message (10008)` | `messageId` is wrong, or message was deleted | Verify the ID is from a still-existing message |
| `Cannot edit a message authored by another user (50005)` | Trying to update / delete a message the bot didn't send | The bot can only edit its own messages; it can delete others' messages only with the *Manage Messages* permission |
| `Bot is in N Discord servers — please specify which one` (from list-channels) | Bot is in multiple servers and `guildId` was left blank | Copy the server ID from the error message and paste it into the `guildId` field |
| `Discord API responded with 429` | Hit Discord's rate limit | Reduce workflow concurrency; this connector doesn't yet auto-retry |

---

## Self-hosting setup (admin-only)

This section is for Twenty server admins. If you're on Twenty Cloud, skip
this — the bot credentials are already configured.

### 1. Create a Discord application

1. Visit https://discord.com/developers/applications and click
   **New Application**.
2. Name it (e.g. *"Twenty Bot"*) and create. Use a dedicated app — don't
   reuse one configured for other bots.
3. Sidebar → **Bot** tab → **Reset Token** → copy the token immediately
   (it's only shown once; if you lose it, reset again).
4. *Recommended:* toggle **Public Bot** OFF so randoms can't invite the
   bot to their servers.

### 2. Generate the invite URL and add the bot to your server(s)

1. In the Discord Developer Portal: sidebar → **OAuth2** → **URL Generator**.
2. **Scopes**: tick `bot`.
3. **Bot Permissions**: tick `Send Messages`, `Manage Messages`,
   `Add Reactions`, `Read Message History`.
4. Copy the generated URL.
5. Open the URL in your browser, pick the Discord server, authorize.
   Repeat for each server you want workflows to post in.

### 3. Wire the bot token into Twenty

1. In Twenty: **Settings → Applications → Discord → Settings tab**
   (gear icon).
2. Paste the bot token into the `DISCORD_BOT_TOKEN` row. Saves on blur.

Workspace users can now use the Discord workflow tools immediately — no
further per-user configuration needed (which is unique vs Linear / Slack
where each user connects their own account).