A Discord bot can send messages to SoAI and post the replies back to Discord. Each Discord channel or direct message becomes a messaging conversation in Chat and uses the model, workspace, sender access, and tools saved with the account.
Prepare the Discord bot
- Sign in to Discord, open its Developer Portal, and create an application, or open the application you want SoAI to use.
- Open General Information and copy the Application ID. Then open Bot and copy or reset the bot token. The public key and client secret are not bot tokens.
- Under Bot > Privileged Gateway Intents, turn on Message Content Intent and save the change. If Discord requires approval for this intent on the application, complete that approval first.
- Under the application's installation settings, include the bot scope for a server install. Give the bot permission to view the intended channels and send messages there, then use the installation link to add it to that server.
Keep the bot token private. SoAI connects to Discord through the Gateway and does not need a public callback address for this provider.
Ordinary Discord messages work without a public SoAI address. Agent questions, tool approvals, and secure secret
links require an HTTPS Public Origin. This can be a private address that the messaging account
owner can reach over the local network or a VPN; Discord does not need to reach it. In the SoAI WebUI, an administrator with
Configuration changes (CONFIG_PATCH) selects the
Settings button at the right of the header, chooses Settings, selects Advanced in the page
header, opens Server, and sets Public Origin. The setting is
SERVER.PUBLIC_ORIGIN.
Do not expose SoAI to the public internet for Discord. Keep it behind the private boundary described in Security hardening and use Network and TLS if the owner needs private remote access.
The Messaging tab requires the SoAI permissions named Model read access (MODEL_READ),
Public inference API access (OPENAI_API), and MCP usage (MCP_USE). These permissions do not require an
external OpenAI account or API key. SoAI also needs an available model and the MCP tool catalog before
Add account can open. Ask an administrator to review your access if the tab is missing.
Add Discord in SoAI
- In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then select Messaging.
- Select Add account.
- Enter an Account label, choose Discord as the Provider, and select the language for SoAI's built-in provider messages under Remote response language.
- Enter the Bot token and Application ID from the same Discord application.
- Choose who may send messages. For restricted access, leave Accept messages from anyone off and enter one numeric Discord user ID per line under Authorized provider senders. Discord lets you copy a user ID after you enable Developer Mode in your Discord settings. If you leave the list empty, SoAI accepts no senders.
- Under Chat execution, select a model and agent mode. Choose the workspace folder and display names, then select Edit parameters for account-specific model parameters.
- Choose any MCP tools the account may use. Turn on Require tool approval if SoAI should send an approval request to the Discord conversation before running a tool that requires it.
- Select Save.
Remote response language controls built-in command, status, error, and interaction messages. To require a language for model answers, select Edit parameters and add that requirement to the System prompt.
SoAI treats each supported message from an allowed user in a channel the bot can view as a prompt. The user does not need to mention the bot or enter a command. Limit the bot's Discord channel permissions if it should answer in only certain channels.
Everyone admitted in the same Discord channel shares one SoAI conversation and its model context. A direct-message channel has its own conversation. Editing or deleting a Discord message does not change the SoAI transcript; send a new correction instead.
A Discord message can contain file attachments with or without text. The server downloads each supported attachment, processes it with the same attachment pipeline used by Chat, and gives it to the model with the message. The file is also visible with that message in the matching Chat conversation. Discord and server file limits still apply. See Attachments and file context for how models use different file types.
Discord supports the text-only commands /help, /status, /cancel, and
/new. See Connect messaging apps to SoAI for what they do and how
to answer agent questions or tool approval requests.
Keep Allow plaintext secret replies off unless you accept the risk of a secret appearing in Discord history or notifications. See Secrets vault for how tools request and store credentials.
Use the conversation in SoAI Chat
You can open the Discord conversation in Chat and send a message there. That message and its immediate reply stay in Chat; neither is copied to Discord. Both remain in the conversation transcript, so the model can use them as context when it answers a later Discord message.
Files attached to a message sent from Chat also stay there. They can affect later model replies, but the server does not forward them to Discord.
Chat locks the model, agent mode, workspace, display names, parameters, and MCP tools saved with the messaging account. To change them, or to update the Discord credentials or sender policy, select the Settings button at the right of the header, choose Settings, select Messaging, and use Edit for the account.
This account can have its own context length and therefore its own effective compaction limit. Under Chat execution, select Edit parameters, then set Context length (tokens) under Model settings. Clear it to use the selected model's default. A lower value gives this account a smaller context budget, so SoAI compacts older context sooner. If a smaller model gives worse answers as a conversation grows, lowering this value can keep its active prompt shorter without changing your other messaging accounts.
Automatic context compaction lets the conversation continue without a fixed message-count limit. SoAI keeps recent turns and may replace older details with a summary before sending the next prompt to the model. See Chat for more about context compaction.
Check the connection
The account row under Settings > Messaging can show Discord Gateway starting while SoAI opens the connection. Wait for Active and Provider connection healthy, then send a message in a channel the bot can view or open a direct message with it. The sender must match the account's sender policy. The setup works when SoAI replies in Discord and the conversation appears in the SoAI Chat sidebar.
Fix common setup problems
If SoAI rejects the token, copy the bot token from Developer Portal > Bot. If it reports an application mismatch, copy the Application ID from the application that owns that bot. If it reports that Message Content intent is unavailable, enable the intent, save the Discord setting, and edit the SoAI account to try again.
A saved account shows Degraded when provider activation fails. Check the Discord bot's channel permissions and the credentials in Settings > Messaging > Edit, then save the account again.