@xdemonme/plugin-notification-telegram

Telegram channel for the NocoBase Notification Manager. Each Notification Manager channel instance uses its own Telegram bot. Users connect individually — Telegram only allows a bot to message a user who has started it first.

Requirements

• NocoBase 2.x
• Plugin @nocobase/plugin-notification-manager enabled

Installation

# From the NocoBase app root
yarn add @xdemonme/plugin-notification-telegram

# Then enable via CLI or Settings → Plugin Manager
yarn nocobase pm:add @xdemonme/plugin-notification-telegram
yarn nocobase pm:enable @xdemonme/plugin-notification-telegram

Quick start

1. Create a bot — talk to @BotFather on Telegram, run /newbot, copy the token.
2. Create a channel — in NocoBase go to Settings → Notification Manager, add a new channel of type Telegram, fill in Bot token, Bot username (without @), and Parse mode.
3. Set up a relay — the plugin does not register a webhook itself. Deploy an external relay (e.g. n8n) that receives Telegram webhook updates and calls POST /api/notificationTelegram:connectFromRelay. See docs/relay-connection.md.
4. Grant relay access — in Settings → Users & Permissions → Roles & Permissions, open the service account role's Plugin settings, expand Telegram settings, and allow the child permission Telegram relay access (ACL snippet pm.notification-telegram.relay). This grants the relay-only notificationTelegram:connectFromRelay action without granting the user-facing Telegram settings page.
5. Connect users — each user opens Settings → Telegram notifications, clicks Connect Telegram, and follows the deep link in Telegram.

Channel configuration

| Field | Description | |--------------|--------------------------------------------------------------------------------------------| | Bot token | Token from @BotFather. Kept server-side; never sent to the client. | | Bot username | Public username without @, e.g. my_company_bot. Used to generate the t.me deep link. | | Parse mode | HTML, Markdown, MarkdownV2, or empty for plain text. |

API reference

All actions are on resource notificationTelegram. Full schema at /admin/settings/api-doc.

| Action | Method | Auth | Description | |----------------------|--------|----------------|------------------------------------------------------------------------------------| | getStatus | POST | logged-in user | Connection status for the current user across all (or one) Telegram channel(s). | | createConnectToken | POST | logged-in user | Issues a one-time token and returns a t.me deep link. | | disconnect | POST | logged-in user | Removes the current user's connection for a channel. | | testSelf | POST | logged-in user | Sends a test message to the user's connected Telegram chat. | | connectFromRelay | POST | service role | Completes a connection after the relay receives the /start update from Telegram. |

Relay architecture

The plugin does not open a webhook port. Instead:

1. Register a Telegram webhook pointing to your relay (e.g. an n8n workflow).
2. When the relay receives a /start connect_<token> message, it calls connectFromRelay with the token and Telegram identity.
3. The plugin validates the token, links the user, and returns a status code.

See docs/relay-connection.md for the full payload schema.

Known limitations

• NocoBase 2.1 only materialises the first entry of indexes[] from a collection definition. The (channelId, telegramChatId) uniqueness is enforced by a migration (20250619000001-add-chat-unique-index), not by the collection schema.
• Connect tokens are cleaned up hourly; rows created before the cleanup was introduced may linger until the next cleanup run.

Development

yarn workspace @xdemonme/plugin-notification-telegram build
yarn workspace @xdemonme/plugin-notification-telegram typecheck
yarn workspace @xdemonme/plugin-notification-telegram test