Discord

The Discord extension gives your agent two capabilities in your Discord server:

• Slash command chat — your users invoke /synapsai text: <message> and the agent replies in the same channel.
• Team notifications — the agent posts automatic notifications (e.g. on negative sentiment, handoff requests, post-tool actions) to the channels you configure, via the notify-team tool.

You can enable just notifications (skip the slash command setup) or both.

Prerequisites

Before setting up the Discord extension, make sure you have:

• A Discord account with access to the Discord Developer Portal.
• A Discord server where you want the agent to operate, with permission to add bots.
• A Discord Application with a Bot user enabled (see step 1 below).

Tip

If you don’t have a Discord Application yet, go to discord.com/developers/applications and click New Application. Give it a name (e.g. “SynapsaiAi”) and an icon — this is how the bot will appear in your server.

Setup

1. Create the Discord Application and Bot

1. In the Discord Developer Portal, open your application.
2. Go to the Bot tab in the left sidebar.
3. Under Token, click Reset Token and copy the new value — this is your Bot Token. Keep it secret; treat it like a password.
4. Under Privileged Gateway Intents, leave everything unchecked — the SynapsAI integration does not require any privileged intents.

2. Invite the bot to your server

1. In the Developer Portal, go to OAuth2 → URL Generator.
2. Under Scopes, check bot and applications.commands.
3. Under Bot Permissions, check Send Messages, Read Message History, and Use Slash Commands.
4. Copy the generated URL at the bottom and open it in your browser.
5. Select your server and click Authorize.

The bot now appears in your server’s member list (offline until you complete setup).

3. Enable the extension in SynapsAI

1. Navigate to your agent’s Extensions page.
2. In the Explore tab, find Discord under the Chat category.
3. Click the card to open the configuration page.

4. Enter your Bot Token

Paste the Bot Token you copied in step 1 into the Bot Token field. SynapsAI will:

• Validate the token immediately by calling the Discord API.
• Auto-populate the Application ID field (you never need to paste it manually).
• Encrypt the token at rest and show only bullet points after saving.

Click Save.

5. Configure notification channels

Under Channels for notify-team, add one row per channel you want your agent to post notifications to. Each row has:

Field	Description
Alias	A short name your agent uses internally (e.g. support, sales, alerts). The LLM picks the alias when calling notify-team.
Channel ID	The Discord channel’s numeric ID. Right-click the channel in Discord → Copy Channel ID (enable Developer Mode in Discord settings if you don’t see this option).

Tip

Make sure your bot is a member of every channel you list. In Discord, right-click the channel → Edit Channel → Permissions → add the bot role.

If you only need notifications (no slash command chat), you can stop here. The agent will start posting to these channels automatically.

6. (Optional) Enable slash command chat

If you want users in your server to chat with the agent using /synapsai, complete the additional setup below.

6a. Paste the Application Public Key

In the SynapsAI Discord wizard, you’ll see an Application Public Key field. Get this value from the Developer Portal:

1. Discord Developer Portal → your application → General Information.
2. Copy the Public Key value (64 hex characters).
3. Paste it into the SynapsAI Application Public Key field and save.

6b. Copy the Interactions Endpoint URL

After saving, SynapsAI displays an Interactions Endpoint URL unique to your agent:

https://api.synapsai.app/v1/{accountId}/discord/{agentKey}

Click the copy button next to it.

6c. Configure the Interactions Endpoint URL in Discord

1. Discord Developer Portal → your application → General Information.
2. Scroll to Interactions Endpoint URL.
3. Paste the URL you copied in step 6b.
4. Click Save Changes.

Discord will send a verification PING to the URL. If everything is configured correctly, the changes save with no error.

Caution

The Interactions Endpoint URL is specific to your agent. If you have multiple agents, each one has its own URL.

6d. Register the /synapsai slash command

The slash command must be registered once per Discord application. Run this from your terminal (replace YOUR_BOT_TOKEN and YOUR_APPLICATION_ID):

curl -X POST "https://discord.com/api/v10/applications/YOUR_APPLICATION_ID/commands" \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "synapsai",
    "description": "Talk to your SynapsAI agent",
    "options": [{
      "type": 3,
      "name": "text",
      "description": "Your message",
      "required": true
    }]
  }'

The command appears in your server within a minute. Users type /synapsai text: <message> to invoke it.

7. Test the connection

Notifications

Have someone send a negative-sentiment message in any conversation (web chat, WhatsApp, etc.). Within a few seconds, the agent should post a notification to the channel matching the configured trigger alias.

Slash command chat

In your Discord server, type:

/synapsai text: ola tudo bem?

You should see “SynapsaiAi is thinking…” within 3 seconds, replaced by the agent’s actual reply within 5-10 seconds.

What your agent can do

Once configured, your Discord agent can:

• Reply to slash commands — /synapsai text: <message> posts the agent’s reply in the same channel where the command was invoked.
• Send team notifications — via the notify-team LLM tool that fires on negative sentiment, handoff requests, post-tool success, and any other condition you wire up in triggers.
• Use your knowledge base, FAQ, and system prompt — all the same configuration that powers your other channels.

How it works

Slash command flow

1. A user in your Discord server types /synapsai text: <message>.
2. Discord delivers the interaction to SynapsAI via the Interactions Endpoint URL.
3. SynapsAI immediately acknowledges with “SynapsaiAi is thinking…” (Discord requires a response within 3 seconds).
4. The agent processes the message asynchronously, consults the knowledge base, and generates a reply.
5. SynapsAI updates the original “thinking…” message with the agent’s reply.

Notification flow

1. The LLM decides to call the notify-team tool with an alias and a message.
2. SynapsAI looks up the channel ID matching the alias in your configuration.
3. SynapsAI’s Discord bot posts the message to that channel.

Inbound UX — what’s supported

The Discord extension uses Discord’s Interactions API (the official slash-command webhook system).

Inbound interaction	Supported?
/synapsai text: <message> slash command	✅ Yes — this is the supported inbound UX
@SynapsaiAi <message> (@mention reply)	❌ Not in this version
Free-form text messages in channels the bot can read	❌ Not in this version
DMs to the bot	❌ Not in this version

Note

@mentions, free-form messages, and DMs would require a long-running real-time connection (Discord’s Gateway WebSocket) plus Discord’s MESSAGE_CONTENT privileged intent — both of which sit outside SynapsAI’s current architecture. Slash commands match the production pattern of every major AI bot on Discord (ChatGPT bot, Claude in Discord, MidJourney). If /synapsai doesn’t fit your use case, reach out and we’ll track demand for free-form message support.

Security

• Your Bot Token is encrypted at rest and never exposed in the UI after saving — the console shows masked bullet points.
• Your Application Public Key is used only to verify the cryptographic signature on incoming interactions; it’s a public value by definition (Discord publishes it openly in the Developer Portal).
• Every incoming interaction is verified with an Ed25519 signature against your Application Public Key before SynapsAI does anything with it. Forged or tampered requests are rejected with HTTP 401.
• If you need to rotate the Bot Token, generate a new one in the Developer Portal and re-paste it in the SynapsAI extension settings.

Troubleshooting

Problem	Solution
Interactions endpoint url could not be verified after saving in Developer Portal	Make sure the Application Public Key in SynapsAI matches the one in Developer Portal → General Information → Public Key exactly. Re-copy + re-save the SynapsAI wizard if unsure.
/synapsai doesn’t appear in the slash command list	Re-register the command (step 6d). Make sure the OAuth invite (step 2) included the applications.commands scope.
Slash command shows “The application did not respond”	Check that the Interactions Endpoint URL in Discord matches the one shown in the SynapsAI wizard. If you re-saved with a wrong value, paste the correct one and save again.
Notifications not arriving in a channel	Confirm the bot is a member of the channel (right-click channel → Edit Channel → Permissions → add the bot). Check the channel ID matches what you pasted in the SynapsAI wizard.
Bot stays offline in server member list	This is expected. The bot only “comes online” when responding to events — it doesn’t maintain a persistent presence.
Slash command reply never replaces “thinking…”	Check the Conversations page for the matching conversation. If the conversation shows the user message but no agent reply, contact support — this usually means the agent couldn’t reach Discord’s API to post the follow-up.

Next steps

• Configure behavior — customize how your agent responds.
• Triggers — wire up notify-team to fire automatically on conditions you care about.
• Operator Handoff — let the agent transfer Discord conversations to a human operator.
• Conversations — review Discord conversation history with the DISCORD origin badge.