> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord

> Chat with your service's agents inside Discord.

The Discord channel connects over the Gateway WebSocket, with the bot sending and receiving messages on a long connection. The Discord channel currently supports:

* **Interactive button approval**: when an agent calls a tool that needs approval, it asks for confirmation as buttons; click to allow or deny;
* **Multimodal input**: receive image and file attachments from users and pass them to the agent;
* **Markdown**: replies render as Markdown, capped at 2000 characters per message, with longer content split automatically.

Connecting takes three steps: create an application and bot on the [Discord Developer Portal](https://discord.com/developers/applications) and get the token, start an agent service to host the channel, then add the Discord channel in the management UI.

## Prerequisites

The Discord channel depends on `discord.py`, installed with the `channel` extra:

```bash Install the dependency theme={null}
pip install "agentscope[channel]"
```

## Create the bot

Create and configure the bot on the [Discord Developer Portal](https://discord.com/developers/applications).

<Steps>
  <Step title="Create an application">
    Click "New Application" to create an app, and record the **Application ID** on the "General Information" page.
  </Step>

  <Step title="Add a bot and get the token">
    Go to the "Bot" page, add a bot, and click "Reset Token" to generate and copy the **Bot Token**. The token is a secret and is shown only once; keep it safe.
  </Step>

  <Step title="Enable Message Content Intent">
    On the "Bot" page, under "Privileged Gateway Intents", enable **MESSAGE CONTENT INTENT**. This is required to read message text; without it, you won't receive message content.
  </Step>

  <Step title="Invite the bot to a server">
    Under "OAuth2 → URL Generator", select the `bot` scope, then the permissions you need (at least "Send Messages" and "Read Message History"), and use the generated link to invite the bot to your server.
  </Step>
</Steps>

## Start the agent service

A channel runs on top of an [agent service](/versions/2.0.6dev/en/deploy/agent-service). Start the service with `create_app` and declare the accepted channel types via `channels`. Channels depend on a message bus (`message_bus`); use `InMemoryMessageBus` for single-machine development, and switch to `RedisMessageBus` for multi-process or multi-node deployment.

```python Start an agent service that hosts the channel theme={null}
from agentscope.app import create_app
from agentscope.app.channel import DiscordChannel
from agentscope.app.message_bus import InMemoryMessageBus
from agentscope.app.storage import RedisStorage
from agentscope.app.workspace_manager import LocalWorkspaceManager

app = create_app(
    storage=RedisStorage(host="localhost", port=6379),
    # In-memory bus for single-machine dev; switch to RedisMessageBus for multi-node
    message_bus=InMemoryMessageBus(),
    workspace_manager=LocalWorkspaceManager(basedir="./workspaces"),
    channels=[DiscordChannel],   # channel types this service accepts
)
# After starting with uvicorn, the channel feature is ready
# uvicorn.run(app, host="0.0.0.0", port=8000)
```

## Add the channel

In the management UI (see the sample frontend [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui)), add a channel through a visual form, with no config to write by hand.

<Steps>
  <Step title="Create a channel and pick Discord">
    On the channel management page, create a channel and choose "Discord" as the platform type.
  </Step>

  <Step title="Fill in the credentials">
    Enter the **Application ID** and **Bot Token** from the previous step into the credential form.
  </Step>

  <Step title="Configure routing rules">
    Choose which agent handles messages and how sessions are scoped. See [Message routing](/versions/2.0.6dev/en/deploy/channel/routing) for what the rules mean.
  </Step>

  <Step title="Save and enable">
    Save and enable the channel; the service connects to Discord immediately and the bot comes online. @mention it in a server channel, or DM it, to begin.
  </Step>
</Steps>

<Note>
  The management UI maps onto the `/channels` endpoints; call them directly when you need to create channels programmatically. See the [API](/versions/2.0.6dev/en/deploy/openapi.json) part of this chapter for the fields.
</Note>

## Platform config

The Discord channel has a few platform-specific switches:

| Field               | Description                                                                                       | Default |
| ------------------- | ------------------------------------------------------------------------------------------------- | ------- |
| `only_at_reply`     | In server channels, reply only when the bot is @mentioned. DMs are unaffected and always answered | `true`  |
| `show_thinking`     | Include the model's reasoning in the reply                                                        | `false` |
| `show_tool_process` | Include tool calls and results in the reply                                                       | `false` |

<Note>
  When routing on `chat_type`, a server channel's value is `guild` and a DM's is `dm`.
</Note>

## Verify and troubleshoot

* Check the channel status in the management UI, or call `GET /channels/{id}/status` to confirm the connection is established.
* If the bot doesn't respond in a server channel, first confirm **MESSAGE CONTENT INTENT** is enabled, then check `only_at_reply` and the @-mention behavior.
* If the bot never comes online, check the Bot Token and that it has been invited to the server.

## Further reading

<CardGroup cols={2}>
  <Card title="Message routing" icon="route" href="/versions/2.0.6dev/en/deploy/channel/routing" cta="Learn more" arrow>
    Route different server channels to different agents.
  </Card>

  <Card title="Custom channel" icon="puzzle-piece" href="/versions/2.0.6dev/en/deploy/channel/custom" cta="Learn more" arrow>
    Connect a platform beyond the built-ins.
  </Card>
</CardGroup>