Chat Bots
A chat bot lets users talk to the AI assistant from a messaging platform: they send the bot a direct message and get the assistant’s reply in the same chat. NetXMS provides chat bots for Telegram, Mattermost, and XMPP.
The bot answers only users that an administrator has mapped to a NetXMS user account, and the AI assistant then works with that user’s access rights. The chat bot also provides a notification channel with the same name, so the same bot account that answers questions also sends alerts.
How a Chat Bot Works
A chat bot holds its own connection to the platform and receives direct messages sent to the bot account. Group chats and channels are ignored.
Each bot has a list of user mappings, each one pairing a platform peer ID with a NetXMS user. Messages from peers that are not in the list are ignored without a reply, so the bot does not reveal itself to strangers. For a mapped peer, the first message opens a session, and the first message for the AI assistant starts a conversation on behalf of the mapped user: everything the assistant reads or changes is checked against that user’s access rights, and the bot adds no rights of its own.
A message that starts with / is a built-in command; any other message goes to the AI assistant.
The bot processes one AI assistant request per session at a time.
Messages for the assistant sent while a request is in progress are combined and sent as the next request; the first of them gets the reply "Still working on your previous request. Your message will be processed next."
Commands and answers to a pending question are processed at once.
When the AI assistant asks for a confirmation or offers a choice (see Approval Workflow), Telegram shows the options as buttons under the message. Mattermost and XMPP show a numbered list of options instead; the user replies with the option number.
A session ends when it has been idle for longer than the bot’s idle timeout (1800 seconds by default), unless a request is in progress or a question is waiting for an answer. A session also ends when its peer’s mapping is removed or changed to another user, and when the bot is deleted. The next message from the peer starts a new conversation.
Message Formatting
AI assistant replies are Markdown. Messages composed by the server, such as command replies and error notices, are plain text, and so are most notifications sent through the bot’s channel. Each platform handles the two kinds differently:
| Platform | Markdown text | Plain text |
|---|---|---|
Telegram |
Converted to Telegram HTML |
Sent as written |
Mattermost |
Posted as is; Mattermost renders it |
Escaped, so it is displayed as written |
XMPP |
Markdown syntax removed (XMPP messages carry no formatting) |
Sent as is |
A Telegram chat bot ignores the ParseMode driver parameter; when it is set, the server logs the warning ParseMode setting "<mode>" is ignored for chat bot.
Before You Begin
-
Configure an LLM provider for the AI assistant (see Getting Started with the AI Assistant). Without a default provider, the bot cannot open AI assistant conversations and replies "Cannot connect to AI assistant. Please contact your NetXMS administrator."
-
Create the bot account on the platform, as described for the matching notification channel driver: Telegram, Mattermost, or XMPP.
-
The chat bot replaces a standalone notification channel that uses the same bot account. Delete such a channel: Telegram delivers incoming messages to only one receiver per bot token, so a channel and a chat bot on the same token take each other’s messages.
Creating a Chat Bot
-
Open Configuration > Chat bots.
-
Click New… and fill in the Create Chat Bot dialog:
- Driver
-
Telegram,Mattermost, orXMPP. Only drivers that support chat bots are listed. - Name
-
Name of the chat bot, also used for its notification channel; filled in from the driver name. The server refuses the name of an existing notification channel (see The Chat Bot Notification Channel).
- Description
-
Optional description.
- Session idle timeout
-
Time in seconds after which an idle session is closed, from 60 to 86400. The default is 1800 seconds.
- AI provider slot (empty for default)
-
Provider slot for the bot’s AI assistant conversations (see Provider Slots). When empty, the
interactiveslot is used. - Driver configuration
-
The parameters of the notification channel driver: all Telegram and XMPP parameters; for Mattermost, only
ServerURL,AuthToken, and the[Channels]section (Color,Footer, andUseAttachmentsare ignored, and messages are posted as plain posts).
-
Add the user mappings.
-
Click OK.
The bot connects to the platform as soon as it is saved. Changing the driver or its configuration reconnects the bot; open sessions stay open.
The chat bot list has these columns:
| Column | Description |
|---|---|
Name |
Name of the chat bot; the icon shows whether the driver is running |
Description |
Description of the chat bot |
Driver |
Driver name |
Health |
Result of the last health check: |
Sessions |
Number of active sessions |
Last message |
Time of the last incoming message, including messages from unmapped peers |
Error message |
Reason why the driver could not start |
Managing chat bots requires the Edit server configuration variables system access right.
Mapping Platform Users
A user mapping pairs a peer ID with a NetXMS user. To add one, click Add… under the mapping list in the chat bot dialog, enter the Platform peer ID, and select the User. The peer ID of an existing mapping cannot be changed; delete the mapping and add a new one.
The peer ID is matched exactly, so enter it as the platform reports it:
| Platform | Peer ID |
|---|---|
Telegram |
Numeric ID of the private chat between the user and the bot, which is the user’s Telegram user ID (for example, |
Mattermost |
Mattermost user ID, a 26-character string (for example, |
XMPP |
Bare JID of the user, without a resource (for example, |
To find a user’s peer ID, set the chatbot debug tag to level 5 (debug chatbot 5 in the server debug console) and ask the user to send any message to the bot.
The server log then contains a line like this:
Chat bot "ops-bot": message from unmapped peer 123456789 (jane) ignored
After the mapping is saved, the user can check it with the /whoami command.
Commands
| Command | Action |
|---|---|
|
Start a new conversation: the AI assistant forgets the conversation so far |
|
Show the mapped NetXMS user name and ID, and the user’s peer ID |
|
List the commands |
Any other text that starts with / gets the reply "Unknown command. Send /help for the list of available commands."
The Chat Bot Notification Channel
Each chat bot registers a notification channel with the same name, which appears in the notification channel list with the driver ChatBot.
Use it in notification actions like any other channel; it sends through the bot’s own connection.
The notification subject, if any, is sent as the first line of the message.
Its state follows the health of the chat bot, and it generates the usual notification channel events (SYS_NOTIFICATION_CHANNEL_DOWN, SYS_NOTIFICATION_CHANNEL_UP, SYS_NOTIFICATION_FAILURE).
The channel takes its configuration from the chat bot and cannot be changed, renamed, or deleted in the channel list. Renaming the chat bot renames the channel, and deleting the chat bot deletes it.
The recipient field accepts:
-
Telegram: a chat ID, or a user name without
@of a user who has already sent a message to the bot -
Mattermost: a Mattermost user ID, a user name prefixed with
@(both send a direct message), or a channel alias from the[Channels]section of the driver configuration -
XMPP: the recipient’s JID
If a notification channel with the bot’s name already exists when the chat bot is created, the bot works but provides no notification channel, and the server logs a warning. Delete the standalone channel and restart the server to register the bot’s channel. Do not rename the chat bot to fix this: the rename is applied to the standalone channel with the old name. For the same reason, never rename a chat bot to the name of an existing notification channel.
Audit Log
Chat bot configuration changes are recorded in the audit log with the user who made them. Session events are recorded with the mapped user as the actor: a session opened for a peer, a session closed (with the reason, such as idle timeout or a changed user mapping), and a question answered by a peer.
Troubleshooting
Use these debug tags:
| Tag | Description |
|---|---|
|
Chat bot sessions, user mapping, commands, and driver health (level 5 logs messages from unmapped peers) |
|
Telegram driver |
|
Mattermost driver, including the WebSocket connection |
|
XMPP driver |
If the bot does not answer:
-
Check that the user’s peer ID is mapped (see Mapping Platform Users).
-
Check that the message is a direct message to the bot; group chats and channels are ignored.
-
For XMPP, messages that the XMPP server delivers late, such as offline messages replayed when the bot connects, are ignored on purpose, so a command sent while the server was down is not run hours later.
-
For Mattermost, the bot reconnects after a lost connection with a delay that starts at 5 seconds and doubles after each failed attempt, up to a maximum of 5 minutes.