Bot Channels

EasyShell supports multiple messaging channels that connect to the AI assistant, allowing your team to interact with EasyShell through Telegram, Discord, DingTalk, Feishu (Lark), Slack, or WeCom (WeChat Work).

Note

Bot channel configuration has been moved to a standalone page. You can now manage all channels in System Management → Bot Configuration.

Channel Overview

Channel	Mode	Public IP Required	Notes
Telegram	Long Polling	No	Auto-polling, no server exposure needed
Discord	REST Polling	No	Polls every 2 seconds
DingTalk	Webhook / Stream	Webhook: Yes / Stream: No	Stream uses WebSocket, no public IP
Feishu	Webhook / Stream	Webhook: Yes / Stream: No	Stream uses WebSocket, no public IP
Slack	Webhook	Yes	Receives messages via Events API
WeCom	Webhook	No	Push-only to group chats

---

Telegram Bot

1. Create a Telegram Bot

1. Search for @BotFather in Telegram
2. Send the /newbot command
3. Follow the prompts to set the bot name and username
4. Upon creation, BotFather returns a Bot Token (format: 123456789:ABCdefGHI-jklMNO...)
5. Save this token securely

2. Get Chat ID

Via API

1. Send a message to the bot (or add the bot to a group and send a message)
2. Open in browser: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
3. Find "chat":{"id": 123456} in the returned JSON — that’s your Chat ID

Via Helper Bot

Search for @userinfobot in Telegram and send any message to get your Chat ID.

3. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → Telegram
2. Fill in the configuration:

Field	Description	Required
Bot Token	Token obtained from BotFather	Yes
Allowed Chat IDs	Comma-separated list of allowed Chat IDs	No (empty = accept all messages)

3. Toggle Enable on
4. The system automatically starts long polling — the bot will receive and reply to messages

Tip

Telegram uses Long Polling mode — no public IP or HTTPS certificate required. Poll timeout is 30 seconds. Single reply message limit is 4096 characters.

---

Discord Bot

1. Create a Discord Bot

1. Visit the Discord Developer Portal
2. Click New Application, enter a name and create
3. Go to Bot in the left menu
4. Click Add Bot to create the bot
5. Click Reset Token to get the Bot Token — save it securely
6. Under Privileged Gateway Intents, enable MESSAGE CONTENT INTENT (required to read message content)

2. Invite the Bot to Your Server

1. Go to OAuth2 → URL Generator in the left menu
2. Under Scopes, check bot
3. Under Bot Permissions, check:
   • Send Messages
   • Read Message History
   • View Channels
4. Copy the generated invite link and open it in your browser
5. Select the target server and confirm authorization

3. Get Guild ID and Channel ID

1. Enable Developer Mode in Discord:
   • User Settings → Advanced → Enable “Developer Mode”
2. Guild ID (Server ID): Right-click the server name → Copy Server ID
3. Channel ID: Right-click the target text channel → Copy Channel ID

4. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → Discord
2. Fill in the configuration:

Field	Description	Required
Bot Token	Discord Bot Token	Yes
Guild ID	Server ID	Yes
Allowed Channel IDs	Comma-separated list of allowed channel IDs	No (empty = listen to all channels)

3. Toggle Enable on

Tip

Discord uses REST polling mode (every 2 seconds) — no public IP required. Single reply limit is 2000 characters. The bot automatically filters its own messages to prevent loops.

---

DingTalk Bot

DingTalk bot supports two modes: Webhook mode and Stream mode.

Stream Mode (Recommended)

Stream mode uses a WebSocket long-lived connection to receive messages — no public IP or HTTPS certificate required. This is the recommended approach.

1. Create an Enterprise Internal App

1. Log in to the DingTalk Open Platform
2. Create an enterprise internal app → Add Bot capability
3. In the app’s Credentials & Basic Info, obtain the Client ID (AppKey) and Client Secret (AppSecret)

2. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → DingTalk
2. Switch mode to Stream
3. Fill in the configuration:

Field	Description	Required
Mode	Select Stream	Yes
Client ID	App’s AppKey	Yes
Client Secret	App’s AppSecret	Yes

4. Toggle Enable on

Tip

In Stream mode, EasyShell connects outbound to DingTalk servers via WebSocket — no public callback URL needed. Disconnections are handled with automatic exponential backoff reconnection.

Webhook Mode

Webhook mode requires your server to have a publicly accessible HTTPS address.

1. Create a DingTalk Custom Bot

1. Open DingTalk desktop client, enter the target group chat
2. Click Group Settings → Smart Group Assistant → Add Bot
3. Select Custom (via Webhook)
4. Set the bot name and avatar
5. For security, select Sign and record the Secret (starts with SEC)
6. Click Finish and copy the generated Webhook URL

2. Configure Callback URL (Receiving User Messages)

Caution

Custom group bots only support pushing messages to groups via Webhook URL — they cannot receive user messages. To receive and auto-reply to user messages, create an enterprise internal application bot on the DingTalk Open Platform and configure a message receiving URL.

Enterprise internal application bot setup:

1. Log in to the DingTalk Open Platform
2. Create an enterprise internal app → Add bot capability
3. Set the message receiving URL to:

   https://<your-server-domain>:<port>/api/v1/webhook/dingtalk

4. Requirements:
   • Must use HTTPS
   • Must be publicly accessible
   • For internal servers, use tools like ngrok or frp for tunneling

3. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → DingTalk
2. Switch mode to Webhook
3. Fill in the configuration:

Field	Description	Required
Mode	Select Webhook	Yes
Webhook URL	DingTalk Webhook URL	Yes
Secret	Signing key (starts with SEC)	Recommended

4. Toggle Enable on

Tip

Signature verification uses HmacSHA256. If you only need to push messages to DingTalk groups (no receiving), just configure the Webhook URL.

---

Feishu (Lark) Bot

Feishu bot supports both Webhook mode and Stream mode.

Stream Mode (Recommended)

Stream mode uses a WebSocket long-lived connection to receive messages — no public IP or HTTPS certificate required.

1. Create a Feishu App

1. Log in to the Feishu Open Platform
2. Create an enterprise self-built app
3. Add Bot capability
4. In Credentials & Basic Info, obtain the App ID and App Secret
5. In Events & Callbacks → Event Configuration, select Long Connection mode
6. Subscribe to events: im.message.receive_v1 (receive messages)

2. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → Feishu
2. Switch mode to Stream
3. Fill in the configuration:

Field	Description	Required
Mode	Select Stream	Yes
App ID	Feishu app’s App ID	Yes
App Secret	Feishu app’s App Secret	Yes

4. Toggle Enable on

Tip

In Stream mode, EasyShell connects outbound to Feishu servers via WebSocket. Replies are sent via the Feishu Reply API. Disconnections are handled with automatic reconnection.

Webhook Mode

Webhook mode requires your server to have a publicly accessible HTTPS address.

1. Create a Feishu App

1. Log in to the Feishu Open Platform
2. Create an enterprise self-built app → Add Bot capability
3. In Credentials & Basic Info, obtain the App Secret (for signature verification)
4. In Events & Callbacks, set the request URL:

   https://<your-server-domain>:<port>/api/v1/webhook/feishu

5. Feishu will send a url_verification request — EasyShell handles this automatically
6. Subscribe to events: im.message.receive_v1 (receive messages)

2. Get Webhook URL (Push Messages)

To push messages to Feishu groups:

1. In Feishu group settings, add a Custom Bot
2. Copy the generated Webhook URL
3. Optionally enable Signature Verification and obtain the key

3. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → Feishu
2. Switch mode to Webhook
3. Fill in the configuration:

Field	Description	Required
Mode	Select Webhook	Yes
Webhook URL	Feishu Webhook URL (for push messages)	Optional
Secret	Signing key (HMAC-SHA256 verification)	Recommended

4. Toggle Enable on

---

Slack Bot

1. Create a Slack App

1. Visit Slack API and click Create New App
2. Choose From scratch, enter the app name and select a workspace
3. Under Event Subscriptions, enable events
4. Set the request URL:

   https://<your-server-domain>:<port>/api/v1/webhook/slack

5. Under Subscribe to bot events, add: message.channels, message.im
6. Under OAuth & Permissions, add Bot Token Scopes:
   • chat:write — Send messages
   • channels:history — Read channel message history
   • im:history — Read direct message history
7. Install the app to your workspace and obtain the Bot Token (starts with xoxb-)
8. In Basic Information, obtain the Signing Secret

2. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → Slack
2. Fill in the configuration:

Field	Description	Required
Webhook URL	Slack Incoming Webhook URL (for push messages)	Optional
Bot Token	Bot Token (starts with xoxb-, for channel replies)	Recommended
Allowed Channel IDs	Comma-separated list of allowed channel IDs	Optional

3. Toggle Enable on

Tip

Slack receives messages via Events API, requiring a publicly accessible HTTPS address. Signature verification uses the Signing Secret to ensure request authenticity. If a Bot Token is configured, the AI replies directly in the channel.

---

WeCom (WeChat Work) Bot

WeCom bot currently supports push-only messaging to group chats.

1. Create a Group Bot

1. In a WeCom group chat, click Group Settings → Add Group Bot
2. Enter the bot name and create
3. Copy the generated Webhook URL

2. Configure in EasyShell

1. Navigate to System Management → Bot Configuration → WeCom
2. Fill in the configuration:

Field	Description	Required
Webhook URL	WeCom Webhook URL	Yes

3. Toggle Enable on

Note

WeCom bot is currently used for push-only scenarios (e.g., scheduled inspection notifications, alert pushes) and does not support receiving and replying to user messages.

---

Conversation Context Settings

Bot channels support persistent conversation context, so the AI remembers previous messages within a session. These settings are configured globally for all channels.

Navigate to System Management → Bot Configuration, and find the Channel Context Settings panel.

Configuration Options

Setting	Description	Default
Context Mode	Persistent — AI remembers conversation history within a session. Stateless — each message is treated independently with no history.	Persistent
Session Timeout	How long (in minutes) before an idle session expires and context is cleared. Set to 0 for no timeout.	30 minutes
Default Provider	AI provider used for bot channel conversations (e.g., OpenAI, Anthropic). If not set, the system’s default AI provider is used.	System default
Default Model	AI model used for bot channel conversations. If not set, the provider’s default model is used.	Provider default

Tip

Each channel can also override the default provider and model individually. Per-channel settings take precedence over the global defaults configured here.

Per-Channel Provider & Model

In each channel’s configuration section, you can optionally set a Provider and Model specific to that channel. This allows different channels to use different AI models. If left empty, the global channel defaults above are used.

Resetting Conversation Context

Users can send the /new command in any bot channel to reset their conversation context and start a fresh session. This clears all previous message history for that user/chat.

Note

Session context is stored in server memory. If the server restarts, all active sessions are cleared and conversations start fresh.

---

Scheduled Task Channel Push

Scheduled inspection tasks and scheduled script execution results can be pushed to designated bot channels. When creating or editing a scheduled task, select the Notification Channel — task results will be automatically sent to the selected channels upon completion.

All enabled channels are supported: Telegram, Discord, DingTalk, Feishu, Slack, and WeCom.

---

Troubleshooting

Bot not responding after configuration?

1. Confirm the channel’s Enable toggle is on
2. Check EasyShell server logs — search for Started channel or Failed to start channel
3. Verify the Bot Token or Webhook URL is correct
4. Confirm an AI model provider is configured (e.g., OpenAI, DeepSeek)

DingTalk / Feishu Stream mode not connecting?

1. Verify the Client ID / App ID and Secret are correct
2. Confirm the app has Bot capability enabled on the open platform
3. Check that outbound network from your server can reach api.dingtalk.com or open.feishu.cn
4. Check logs for WebSocket connection errors
5. Stream mode auto-reconnects with exponential backoff — wait a few seconds

How to restart Telegram / Discord bot?

In Bot Configuration, turn off the channel’s Enable toggle, wait a few seconds, then turn it back on. The system will automatically stop the old connection and establish a new one.

DingTalk bot not receiving messages (Webhook mode)?

1. Confirm you’re using an enterprise internal application bot (not a custom group bot) with a message receiving URL configured
2. Verify the callback URL https://<domain>/api/v1/webhook/dingtalk is publicly accessible
3. Check that the signing Secret matches the DingTalk Open Platform configuration
4. Check server logs for signature verification failures

Feishu bot not receiving messages (Webhook mode)?

1. Verify the callback URL https://<domain>/api/v1/webhook/feishu is publicly accessible
2. Confirm the url_verification challenge completed successfully (EasyShell handles this automatically)
3. Confirm you’ve subscribed to the im.message.receive_v1 event
4. Check that the signing Secret matches the Feishu Open Platform configuration

Slack bot not receiving messages?

1. Verify the Events API request URL https://<domain>/api/v1/webhook/slack is publicly accessible
2. Confirm you’ve subscribed to message.channels and message.im events
3. Confirm Bot Token Scopes include chat:write and channels:history
4. Check that the Signing Secret is correct

How to check bot status?

Check the EasyShell server startup logs:

Started channel: telegram                — Telegram bot started
Started channel: discord                 — Discord bot started
DingTalk bot started (stream mode)       — DingTalk bot started (Stream)
DingTalk bot started (webhook mode)      — DingTalk bot started (Webhook)
Feishu bot started (stream mode)         — Feishu bot started (Stream)
Feishu bot started (webhook mode)        — Feishu bot started (Webhook)
Slack bot started (webhook mode)         — Slack bot started
WeChat Work bot started (webhook mode)   — WeCom bot started
Failed to start channel: xxx             — Startup failed, check error details

Bot doesn’t remember conversation history?

1. Check that Context Mode is set to Persistent (not Stateless) in Channel Context Settings
2. Verify the Session Timeout hasn’t expired — if the user was idle longer than the configured timeout, the session was cleared
3. Check server logs for Session expired for messages indicating timeout-based cleanup
4. Remember that server restarts clear all session context

How to use different AI models for different channels?

Set the Provider and Model fields in each channel’s individual configuration section. For example, you can use GPT-4o for Telegram and Claude for Discord. If a channel’s provider/model is not set, it falls back to the global channel defaults, then to the system AI settings.