IM Channel Integration

Prerequisites: You must first create a Bot (Bot Management) before configuring messaging channels for it. If you are not yet familiar with the platform’s core architecture, we recommend reading Core Concepts first.

A Gateway is the messaging bridge between an external IM platform and a Monstrum Bot. Once a Gateway is configured, users can chat with the Bot directly from popular IM platforms such as Slack, 飞书 (Feishu), Telegram, and more — without needing to access the Monstrum admin interface.

Overview

What Is a Gateway

A Gateway, also referred to as a “messaging channel,” is Monstrum’s unified abstraction for external IM messaging channels. Each Gateway configuration represents a message pathway from an external IM platform to a specific Bot within the platform.

Key characteristics:

One Bot, multiple channels — A single Bot can be connected to multiple channels such as Slack, 飞书 (Feishu), and Telegram simultaneously. Messages from different channels are all handled by the same Bot.
One channel, one Bot — Each Gateway configuration can only be associated with one Bot. If you need to connect multiple Bots to the same IM platform, create multiple Gateways.
Non-blocking delivery — When a Webhook request arrives from an external IM platform, the platform immediately returns a 200 response. Messages are asynchronously routed to the Bot, and the Bot’s replies are asynchronously delivered back to the IM channel.
Credential security — IM platform credentials such as Tokens and Secrets are encrypted at rest within the platform and displayed in masked form on list and detail pages.

Message Flow

When a user sends a message in an IM platform, it goes through the following pipeline:

User sends a message in IM
    ↓
IM platform pushes the message to Monstrum's Webhook URL
    ↓
Gateway adapter verifies the request signature and parses the message format
    ↓
Command interception (/link, /help, and other platform commands are handled directly without reaching the Bot)
    ↓
Message policy filtering (reply scope, trigger mode, user/channel allowlists, etc.)
    ↓
Message is converted to the internal unified format (MessageEnvelope) and routed to the associated Bot
    ↓
Bot processes the message and generates a reply
    ↓
Gateway delivers the reply back to the original IM channel

Supported Channel Types

Channel	Type Identifier	Description
Slack	`slack`	Slack workspace; receives messages via Events API
飞书 (Feishu)	`feishu`	Feishu/Lark app; receives messages via event subscriptions
Telegram	`telegram`	Telegram Bot; supports both polling and Webhook modes
Discord	`discord`	Discord server Bot
钉钉 (DingTalk)	`dingtalk`	DingTalk enterprise internal app Bot
企业微信 (WeCom)	`wecom`	WeCom self-built app; uses message encryption/decryption
QQ 机器人 (QQBot)	`qqbot`	QQ Open Platform Bot; supports group and direct messages
LINE	`line`	LINE Messaging API
WhatsApp	`whatsapp`	WhatsApp Business API
Webhook	`webhook`	Generic Webhook; suitable for custom system integrations

Configuration Workflow

Messaging channels are configured on each Bot’s detail page.

Adding a Channel

Navigate to the target Bot’s detail page
Switch to the Messaging Channels tab
Click the Add Channel button
Select the channel type and fill in the required credentials

Common Form Fields

All channel types include the following common fields:

Field	Description
Name	Display name for the channel, e.g., “Customer Support Slack Channel” or “Ops Feishu Group”
Channel Type	Select the IM platform from the dropdown list
Enable Immediately	Whether to start receiving messages right after saving

After selecting the channel type, the form dynamically displays the platform-specific credential fields required for that type.

Webhook URL

Once a Gateway is successfully created, the platform generates a unique Webhook URL in the following format:

https://{your-domain}/gateway/{channel-type}/{config-id}

You need to enter this URL in the corresponding IM platform’s Webhook or event subscription settings so the IM platform can push messages to Monstrum.

In the Gateway list, click the copy button next to the Webhook URL to quickly copy it.

Slack

Through the Slack Events API, Monstrum can receive messages from a Slack workspace and reply to them.

Prerequisites (on Slack)

Create a Slack App — Visit Slack API and click Create New App > From scratch
Configure Bot Token permissions — Go to OAuth & Permissions and add the following under Bot Token Scopes: chat:write, app_mentions:read, im:history, im:write. Optionally add channels:history and groups:history as needed
Install to workspace — Click Install to Workspace and obtain the Bot User OAuth Token (starts with xoxb-)
Obtain the Signing Secret — Find it under Basic Information > App Credentials

Configure in Monstrum

In the Add Gateway form, select the Slack type and fill in:

Field	Description
Signing Secret	The Slack App’s signing secret, used to verify requests from Slack
Bot Token	Bot User OAuth Token, starting with `xoxb-`

Configure Event Subscriptions

After creating the Gateway, you need to enter the generated Webhook URL in your Slack App:

In the Slack App settings page, go to Event Subscriptions
Enable Enable Events
Enter the Webhook URL generated by Monstrum in the Request URL field
Slack will send a challenge request to verify the URL; Monstrum responds automatically
Once verified, under Subscribe to bot events, add:
- message.im — Direct messages
- app_mention — @Bot messages
- message.channels — Public channel messages (optional)
Save changes

Message Behavior

Direct messages: Users message the Slack Bot directly, and the Bot replies in the same conversation
Group chats: By default, the Bot only responds when @mentioned (controlled by trigger mode)
Thread replies: The Bot automatically replies within the message thread, preserving conversational context

飞书 (Feishu)

飞书 (Feishu), also known as Lark, receives messages through its event subscription mechanism.

Prerequisites (on Feishu)

Create an app — Visit the Feishu Open Platform, go to the Developer Console, and create an enterprise self-built app
Obtain credentials — Find the App ID and App Secret on the Credentials & Basic Info page
Configure event subscriptions — On the Events & Callbacks page, obtain the Verification Token; you will enter the Webhook URL later
Configure permissions — Request im:message, im:message.group_at_msg, and im:message.p2p_msg
Publish the app — Permissions take effect after review and publication; add the app to the target group chats

Configure in Monstrum

In the Add Gateway form, select the 飞书 (Feishu) type and fill in:

Field	Description
App ID	Feishu app’s App ID
App Secret	Feishu app’s App Secret
Verification Token	Event subscription verification Token, used to verify event requests pushed by Feishu

Configure Event Subscription URL

After creating the Gateway:

Copy the Webhook URL generated by Monstrum
On the Feishu Open Platform’s Events & Callbacks page, enter this URL
Feishu will send a verification request; Monstrum responds automatically
In the Event List, subscribe to the following event:
- im.message.receive_v1 — Receive message event

Message Behavior

Direct messages: Users message the app directly in Feishu
Group chats: After adding the app to a group chat, users @mention the app to send messages
Bot replies appear in the conversation under the app’s identity

Receives and replies to messages through the Telegram Bot API.

Prerequisites (on Telegram)

Create a Bot — Search for @BotFather in Telegram, send /newbot, and follow the prompts to obtain a Bot Token
Configure Bot properties (optional) — Use BotFather commands such as /setdescription, /setuserpic, and /setcommands to customize the Bot’s profile
Group chat settings (if needed) — Use /setjoingroups to allow joining groups, and /setprivacy to disable Privacy Mode so the Bot can receive all group messages

Configure in Monstrum

In the Add Gateway form, select the Telegram type and fill in:

Field	Description
Bot Token	Token obtained from @BotFather
Proxy (optional)	HTTP proxy address, e.g., `http://127.0.0.1:7890`, for network-restricted environments

Connection Mode

The Telegram adapter uses long polling mode by default, actively pulling messages without requiring a Webhook URL. Polling starts automatically when the platform launches.

If your deployment environment has a publicly accessible address, you can also use Webhook mode for lower message latency.

Message Behavior

Direct messages: Users message the Bot directly, and the Bot replies in the same conversation
Group chats: The Bot must be added to the group. By default, it only responds when @mentioned (this can be changed by disabling Privacy Mode to receive all messages)
The Bot supports replying to specific messages (Reply), maintaining contextual association

Discord

A community-oriented instant messaging platform widely used by gaming and developer communities.

Prerequisites (on Discord)

Create an application — Visit the Discord Developer Portal and create a new application
Create a Bot — On the Bot page, click Add Bot, enable Message Content Intent (required), and copy the Bot Token
Invite the Bot to a server — Under OAuth2 > URL Generator, select the bot scope and check Send Messages, Read Message History, and View Channels permissions. Use the generated link to invite the Bot

Configure in Monstrum

In the Add Gateway form, select the Discord type and fill in:

Field	Description
Discord Bot Token	Bot Token obtained from the Developer Portal
Allowed Server IDs (optional)	Restrict the Bot to specific servers only; separate multiple IDs with commas

If no allowed server IDs are specified, the Bot will respond to messages in all servers it has joined.

Obtaining a Server ID

In Discord, enable Developer Mode (User Settings > Advanced > Developer Mode), then right-click on a server icon and select Copy Server ID.

Message Behavior

Direct messages: Users can send private messages to the Bot directly
Server channels: The Bot receives messages in channels where it has access
By default, the Bot only responds when @mentioned (adjustable via trigger mode)

钉钉 (DingTalk)

An enterprise collaboration platform by Alibaba, widely used by businesses in China.

Prerequisites (on DingTalk)

Create an application — Visit the DingTalk Open Platform and create an enterprise internal Robot-type application
Obtain credentials — Find the AppKey (ClientID) and AppSecret (ClientSecret) on the Basic Information page
Configure the robot — On the Robot & Message Push page, enable the feature; you will enter the Webhook URL later
Publish the application — After requesting permissions, create a release version and submit it for review

Configure in Monstrum

In the Add Gateway form, select the 钉钉 (DingTalk) type and fill in:

Field	Description
App AppKey	DingTalk app’s AppKey (ClientID)
App AppSecret	DingTalk app’s AppSecret (ClientSecret)

Configure Message Receiving URL

After creating the Gateway:

Copy the Webhook URL generated by Monstrum
On the DingTalk Open Platform’s Robot & Message Push page, enter this URL
DingTalk will push messages sent to the robot through this URL

Message Behavior

Direct messages: Users message the robot directly
Group chats: After adding the robot to a group chat, users @mention the robot to send messages
DingTalk uses signature verification to ensure message authenticity

企业微信 (WeCom)

An enterprise communication platform by Tencent. Message transmission uses AES-256-CBC encryption, providing a high level of security.

Prerequisites (on WeCom)

Create a self-built application — Log in to the WeCom Admin Console, go to App Management > Self-built, and create an application
Obtain credentials — CorpID (at the bottom of the “My Enterprise” page), AgentID and Secret (on the app detail page)
Configure message receiving — In the app’s Receive Messages settings, set the URL (enter the Webhook URL). The system will auto-generate a Token and EncodingAESKey; save these for later
Configure trusted domain — If needed, add the Monstrum domain in the app settings

Configure in Monstrum

In the Add Gateway form, select the 企业微信 (WeCom) type and fill in:

Field	Description
Corp ID (CorpID)	The enterprise’s unique identifier
App AgentID	The self-built app’s AgentID
App Secret	The app’s secret key
Callback Token	Token generated in the message receiving configuration
EncodingAESKey	Message encryption/decryption key generated in the message receiving configuration

Message Encryption

WeCom uses AES-256-CBC encryption for message transmission:

The encryption key is derived from the EncodingAESKey
The CorpID is embedded in messages for source verification
Monstrum handles encryption and decryption automatically; no manual action is required

Message Behavior

Direct messages: Users message the app in WeCom
Group chats: After adding the app to a group chat, users @mention the app to send messages
All messages are encrypted during transmission, ensuring enterprise data security

QQ 机器人 (QQBot)

Built on the QQ Open Platform, QQBot supports providing AI services in QQ groups and direct messages.

Prerequisites (on QQ Open Platform)

Create an application — Visit the QQ Open Platform and create a Bot application
Obtain credentials — Record the AppID and AppSecret
Configure event subscriptions — In Development Settings, configure the message receiving URL; you will enter the Webhook URL later
Sandbox environment (optional) — During development, you can use the sandbox environment for testing

Configure in Monstrum

In the Add Gateway form, select the QQ 机器人 (QQBot) type and fill in:

Field	Description
App ID	QQ Open Platform application AppID
App Secret	Application AppSecret

Verification Mechanism

The QQ Open Platform uses Ed25519 signature verification:

The platform automatically derives an Ed25519 key pair from the AppSecret
During verification requests, URL verification events (op=13) automatically return a signed challenge
This process is fully automatic and requires no user intervention

Message Behavior

Group chats: Users @mention the Bot in a group to send messages; the event type is GROUP_AT_MESSAGE_CREATE
Direct messages: Users message the Bot directly; the event type is C2C_MESSAGE_CREATE
QQBot uses the OpenID system to identify users and groups

LINE

A widely used instant messaging platform in Japan, Southeast Asia, and other regions.

Prerequisites (on LINE)

Create a Channel — Visit the LINE Developers Console, create a Provider, then create a Messaging API type Channel
Obtain credentials — Channel Access Token (generated in the Messaging API tab) and Channel Secret (in the Basic Settings tab)
Configure Webhook — In the Messaging API tab, enable Use webhook; you will enter the Webhook URL later
Disable auto-reply (recommended) — Disable the auto-response message in the LINE Official Account Manager

Configure in Monstrum

In the Add Gateway form, select the LINE type and fill in:

Field	Description
Channel Access Token	Long-lived access token for the Messaging API
Channel Secret	The Channel’s secret, used to verify Webhook request signatures

Message Behavior

One-on-one chats: Users add the official account as a friend and message it directly
Group chats: Add the official account to a group to receive messages
LINE uses Webhook mode and requires a publicly accessible URL

Sends and receives messages through the WhatsApp Business API.

Prerequisites (on Meta)

Create an application — Visit Meta for Developers, create a Business type application, and add the WhatsApp product
Obtain credentials — Access Token (generate a permanent token in API settings), Phone Number ID (business number ID), App Secret (optional, found in Basic Settings)
Configure Webhook — In the WhatsApp Webhook settings, enter the Webhook URL, set a custom Verify Token (must match the one in Monstrum), and subscribe to the messages field

Configure in Monstrum

In the Add Gateway form, select the WhatsApp type and fill in:

Field	Description
Access Token	Permanent access token for the WhatsApp Business API
Phone Number ID	ID of the WhatsApp business phone number
Verify Token	Webhook verification token; must match the one set on the Meta platform
App Secret (optional)	Meta app secret, used to verify Webhook request signatures. Recommended for enhanced security

Webhook Verification

WhatsApp’s Webhook verification has two steps:

GET verification — Meta sends a GET request to the Webhook URL with hub.mode=subscribe and hub.verify_token parameters. Monstrum automatically verifies the Verify Token and returns the hub.challenge
POST delivery — After verification passes, messages are delivered to the same URL via POST

Message Behavior

WhatsApp only supports one-on-one direct messages; Bots in group chats are not supported
Users send a message to the WhatsApp business number to trigger a Bot reply
Note WhatsApp’s 24-hour conversation window rule: you can reply freely within 24 hours after the user sends a message. After that, template messages are required

Webhook (Generic)

Webhook is the most flexible integration method, suitable for custom system integrations. You can push messages to Monstrum from any system capable of sending HTTP requests.

Use cases include internal system integrations (monitoring alerts, ticketing, CI/CD), custom IM integrations, API-driven automation, and development/debugging.

Configure in Monstrum

In the Add Gateway form, select the Webhook type and fill in:

Field	Description
Name	Resource name, e.g., “Monitoring Alert Channel”
Associated Bot	Select the Bot that will process messages
Callback URL (optional)	Bot replies are sent to this URL. If left empty, replies are only recorded within the platform
Signing Secret (optional)	Used to verify request signatures. If set, each request must include the `X-Webhook-Secret` header

Sending Messages to the Webhook

After creating the Gateway, obtain the generated Webhook URL and send POST requests to it.

Request format:

Field	Type	Required	Description
`source`	string	No	Message source identifier; defaults to `webhook`
`user_id`	string	Yes	User ID
`channel_id`	string	No	Channel/group chat ID
`text`	string	Yes	Message text
`callback_url`	string	No	Per-request callback URL (overrides the Gateway’s configured callback URL)
`metadata`	object	No	Additional metadata

Signature Verification

If a signing secret is configured, you must include the following HTTP header when sending requests:

X-Webhook-Secret: {your-configured-signing-secret}

Requests that are missing the header or have a mismatched secret will be rejected.

Reply Delivery

Bot replies are asynchronously delivered via HTTP POST to the configured callback URL. If a callback_url is also provided in an individual request, the per-request URL takes precedence.

Message Policies

Message policies allow fine-grained control over how a Bot responds in IM channels. On the Gateway management page or the Messaging Channels tab of the Bot detail page, click the Manage button for a Gateway to configure its message policies.

Reply Scope

Controls which types of conversations the Bot responds to:

Option	Description
All	Reply to both direct and group messages (default)
Direct messages only	Reply only to direct messages; group messages are silently ignored
Group chats only	Reply only to group messages; direct messages are silently ignored

Bots for internal teams are typically set to All; group-dedicated Bots use Group chats only; Bots handling sensitive information use Direct messages only.

Trigger Mode

Controls under what conditions the Bot responds to messages:

Option	Description
Smart	In group chats, only reply when @mentioned; in direct messages, reply to all messages (default, recommended)
All messages	Reply to all messages regardless of whether the Bot is @mentioned
@Bot only	Only reply to messages that explicitly @mention the Bot, including direct messages

Smart mode works well for most scenarios. Dedicated channels (where users only interact with the Bot) can use All messages; multi-user groups should use @Bot only to avoid unintended triggers.

User Filtering

Control which users can interact with the Bot through allowlists and blocklists:

Setting	Description
Allowed users	User ID allowlist. If specified, only messages from users on this list will be processed
Blocked users	User ID blocklist. Messages from users on this list are silently ignored

Allowlists and blocklists use IM platform user IDs (not usernames)
An empty allowlist means no allowlist restriction is applied (all users are permitted)
The blocklist takes priority over the allowlist

Channel Filtering

Control which channels the Bot responds to through allowlists and blocklists:

Setting	Description
Allowed channels	Channel ID allowlist. If specified, only messages from channels on this list will be processed
Blocked channels	Channel ID blocklist. Messages from channels on this list are silently ignored

Uses IM platform channel/group IDs
An empty allowlist means no allowlist restriction is applied
Useful when the Bot has joined multiple channels but should only operate in specific ones

Policy Evaluation Order

Message policies are evaluated in the following order. If any step fails, the message is silently ignored:

Reply scope — Does the conversation type match?
Trigger mode — Is the trigger condition satisfied?
User allowlist — Is the user on the allowed list (if configured)?
User blocklist — Is the user on the blocked list?
Channel allowlist — Is the channel on the allowed list (if configured)?
Channel blocklist — Is the channel on the blocked list?

Admin Binding

Each Gateway supports binding one IM administrator. The admin can execute platform management commands directly within the IM client, without needing to log in to the Monstrum admin interface.

Binding Process

In the Monstrum admin interface, locate the target Gateway
In the Admin Binding section, click Regenerate Binding Code
The system generates a one-time binding code
Share the binding code with the IM user who should become the admin
That user sends the following command to the Bot via direct message in the IM:

/link {binding-code}

On successful binding, the system replies with “Admin linked successfully!”
The binding code is invalidated after use and cannot be reused

Admin Commands

Once bound, the admin can use the following management commands in the IM:

Command	Description	Permission Required
`/link {code}`	Bind as admin	All users, direct message only
`/unlink`	Unbind admin	Admin, direct message only
`/status`	View Bot status and policy information	Admin, direct message only
`/chathis on\|off\|clear`	Manage channel conversation persistence	Admin, direct message and group chat
`/help`	Display list of available commands	All users, direct message and group chat

Command Details

/status

View status information for the current Gateway, including:

Associated Bot name
Gateway channel type
Admin binding status
Current message policy configuration

/chathis (Conversation Persistence Management)

Manage conversation persistence for the current channel:

/chathis on — Enable conversation persistence; the Bot will remember the conversation history in the channel
/chathis off — Disable conversation persistence; each conversation starts fresh
/chathis clear — Clear the conversation history for the current channel without changing the persistence setting

This command can be used in group chats and applies to the current channel.

/help

Displays a list of all available commands, including platform built-in commands and workflow commands bound to the Bot. If the Bot is associated with workflows that support IM command triggers, those commands will also appear in the /help output.

Important Notes

Each Gateway can have only one admin at a time
Binding codes are single-use; they are invalidated after use or when a new code is generated
Management commands (except /link and /help) can only be executed by the admin
/link and /unlink can only be used in direct messages to prevent binding code exposure
/help and /chathis can be used in group chats

Gateway Status Management

Status Descriptions

Status	Description
Connected	Gateway is operating normally; it can receive and send messages
Disconnected	Gateway has been created but has not yet received any messages, or the adapter has not started
Error	Gateway encountered an issue, such as invalid credentials or a broken connection

Enable, Edit, and Delete

Enable/Disable — Use the toggle switch in the list. Disabling preserves the configuration; re-enabling restores it
Edit — Click the edit button to modify the configuration. Leaving credential fields empty keeps their existing values
Delete — This is an irreversible operation. After deletion, IM users can no longer interact with the Bot. The Webhook configuration on the IM platform side must be removed manually

Chatting with the Bot via IM

Messages received through a Gateway enter the Bot’s conversation system. For details, see Chat Interaction. Here is a brief overview of IM channel-specific behavior:

Conversation isolation — Messages from different IM channels belong to different conversations. Within the same channel, messages from different users belong to the same conversation (in group chat scenarios).
Conversation persistence — Conversations expire after 30 minutes of inactivity. Admins can enable persistence with /chathis on, which automatically saves the conversation history when it expires and restores context in the next conversation. When a conversation exceeds 80 messages, it is automatically compressed (an LLM summarizes older messages while retaining recent ones).
Deduplication — The platform has built-in deduplication. Even if the IM platform pushes the same message multiple times due to network instability, the Bot processes it only once.

FAQ

Gateway Status Shows “Disconnected”

Possible causes:

The Gateway was just created and has not yet received any messages from the IM platform
The Webhook URL is not configured correctly on the IM platform
Platform credentials (Token, Secret, etc.) were entered incorrectly
Network issues are preventing the IM platform from reaching Monstrum’s Webhook URL

Troubleshooting steps:

Verify that Monstrum is accessible from the public internet (the IM platform needs to be able to send HTTP requests to the Webhook URL)
Confirm the Webhook URL has been correctly entered in the IM platform’s settings
Check that credentials are correct (you can edit the Gateway to re-enter them)
Review the IM platform’s Webhook logs for any error messages

Bot Does Not Reply to IM Messages

Possible causes:

The Gateway is not enabled
The message policy’s trigger mode is restricting responses
The user is not on the allowlist, or has been added to the blocklist
The channel is not on the allowlist, or has been added to the blocklist
The associated Bot has a configuration issue (e.g., no LLM provider configured)

Troubleshooting steps:

Confirm the Gateway is enabled
Check the message policy’s reply scope and trigger mode settings
Review the user and channel filter lists
Chat with the Bot directly in the Monstrum admin interface to confirm it is functioning properly
Check the Bot’s execution history to verify whether the message was received

Duplicate Replies

The platform has built-in deduplication, so duplicates should not normally occur. Check whether multiple Gateways are pointing to the same channel, or whether the IM platform is pushing the same Webhook event multiple times.

Channel-Specific Verification Failures

Slack URL verification failed — Ensure Monstrum is running and publicly accessible, and that the Signing Secret is entered correctly
Feishu events not being delivered — Confirm the Verification Token matches, that the im.message.receive_v1 event is subscribed, and that the app has been published
WeCom message decryption failed — Verify the EncodingAESKey (watch for extra spaces) and CorpID are correct
WhatsApp Webhook verification failed — Confirm the Verify Token matches and that the Webhook URL is reachable via GET

Best Practices

Always configure signature verification — For Webhook-type Gateways, always set a signing secret. For other types, ensure all credential fields are completely filled in
Use user allowlists — When a Bot should only serve specific users, configure an allowed users list
Restrict servers/channels — For platforms like Discord, configure allowed server IDs to limit the Bot’s operating scope
Test before going live — After creating a Gateway, verify message sending and receiving in a test channel first
Use Smart trigger mode — The default mode works well for most scenarios and avoids excessive interruptions in group chats
Disable instead of delete — For channels not currently needed, disable them rather than deleting them, making it easy to restore later
Use descriptive names — Include the purpose and platform, e.g., “Customer Support Slack Channel,” “Feishu - Engineering Group,” or “Webhook (Testing)”

Edit this page on GitHub