Discord API Setup

Admin walkthrough for the Discord integration. End-user flow: Connections → Discord.

Overview

Form field	Options key
Client ID	discord_client-id
Client Secret	discord_client-secret
Bot Token	discord_bot-token
Status	discord_integration_status

ENV fallback: DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_BOT_TOKEN.

Discord = OAuth + Bot

Discord requires three secrets: an OAuth Client ID/Secret pair (so users can authorize Sosyabot), plus a Bot Token (so Sosyabot can post messages on the bot's behalf).

Step-by-step on discord.com/developers/applications

1. Create a new application

https://discord.com/developers/applications → New Application → name it (e.g. "Sosyabot").

2. Configure OAuth2

In the app's left sidebar click OAuth2.

• Redirects: add

  https://app.sosyabot.com/api/v1/auth/discord/callback

• Client ID: copy the value at the top of the OAuth2 page.
• Client Secret: click Reset Secret the first time → copy the revealed value (Discord displays it once).

3. Add a Bot

Left sidebar → Bot → Add Bot (confirm).

• Privileged Gateway Intents: Sosyabot doesn't need Presence or Members intents; leave them off.
• Bot Token: click Reset Token to generate a fresh token, copy it immediately. Discord shows the bot token only at reset.

Token security

Anyone with the bot token controls the bot. Treat it like a password. If leaked, Reset Token invalidates the leaked one and forces every connected guild to re-add the bot.

4. Configure invite permissions

Left sidebar → OAuth2 → URL Generator:

• Scopes: check bot.
• Bot Permissions: check Send Messages (additional perms only if you'll need them).

Copy the generated URL — this is the install URL admins will use to invite the bot to a guild later.

Pasting into Sosyabot admin panel

/admin/api-integration/discord:

1. Client ID: paste from OAuth2 page.
2. Client Secret: paste the revealed secret.
3. Bot Token: paste the bot token.
4. Status: Enable.
5. Save → Test credentials.

Failure: Discord integration disabled: client id/secret/bot token not configured.

Verification

1. /app/channels → Connect → Discord. Discord prompts you to invite the bot to a guild — pick a guild you administer.
2. Approve OAuth scopes + bot invite. The bot must be approvable by a guild admin.
3. Sosyabot lists writable text channels in that guild; pick one as default.
4. Send a test message from /app/publishing and confirm it appears in the Discord channel.

Troubleshooting

Symptom	Cause	Fix
Discord integration disabled: client id/secret/bot token not configured	Admin + ENV missing one of the three	Provide all three; Discord requires the bot token in addition to OAuth.
Bot invite shows Missing Permissions	The user doesn't have Manage Server on the target guild	Pick a guild they administer, or get a guild admin to approve the bot.
Connect succeeds but no channels listed	Bot was invited but lacks Send Messages on every channel	Adjust channel permissions in Discord; ping @bot in a channel to test.
Sudden 401 Unauthorized	Bot token reset or app deleted	Regenerate the bot token in Developer Portal and update the admin panel; existing channel bindings keep working but message sending will fail until updated.

ENV fallback

DISCORD_CLIENT_ID=<your client id>
DISCORD_CLIENT_SECRET=<your client secret>
DISCORD_BOT_TOKEN=<your bot token>

After editing .env run ./service.sh restart api.

Related

OAuth Credentials overview

Discord user-side connect

OAuth Callback URLs