Skip to content

SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.

feat(notification-channels): add the telegram channel form (#13119)

Ashwin Bhatkalfcb685bf3798
diff --git a/frontend/public/locales/en/channels.json b/frontend/public/locales/en/channels.json
index 5a10405e5f..164cbd4eaf 100644
--- a/frontend/public/locales/en/channels.json
+++ b/frontend/public/locales/en/channels.json
@@ -187,5 +187,24 @@
"slack_channel_help": "Specify channel or user, use #channel-name, @username (has to be all lowercase, no whitespace)",
"api_key_required": "API Key is mandatory",
"to_required": "To field is mandatory",
- "channel_name_required": "Channel name is mandatory"
+ "channel_name_required": "Channel name is mandatory",
+ "bot_token_required": "Bot token is mandatory for creating a telegram channel",
+ "chat_id_required": "Chat ID is mandatory for creating a telegram channel",
+ "telegram_tip": "Create a bot with @BotFather, add it to the chat, then paste its token and the chat's numeric id below.",
+ "telegram_tip_link": "Learn how",
+ "field_telegram_bot_token": "Bot token",
+ "tooltip_telegram_bot_token": "The token BotFather returns, in the form 123456789:AA...",
+ "field_telegram_chat_id": "Chat ID",
+ "tooltip_telegram_chat_id": "The numeric chat the bot posts to, negative for groups and channels. Telegram's @username form is not accepted.",
+ "placeholder_telegram_chat_id": "e.g. -1001234567890",
+ "field_telegram_message_thread_id": "Message thread ID",
+ "tooltip_telegram_message_thread_id": "Posts into one message thread of a forum group. Leave empty to post in the group itself.",
+ "field_telegram_title": "Title",
+ "tooltip_telegram_title": "Sent in bold above the message. Telegram HTML, so interpolated values are escaped.",
+ "field_telegram_message": "Message",
+ "tooltip_telegram_message": "Template for the message body. Telegram HTML, so interpolated values are escaped.",
+ "field_telegram_api_url": "Bot API URL",
+ "tooltip_telegram_api_url": "Point at a self-hosted Bot API server. Leave empty to use Telegram's.",
+ "field_telegram_disable_notifications": "Send silently",
+ "tooltip_telegram_disable_notifications": "Delivers without a sound or vibration on the recipients' devices."
}
diff --git a/frontend/src/container/FormAlertChannels/Settings/Telegram.tsx b/frontend/src/container/FormAlertChannels/Settings/Telegram.tsx
new file mode 100644
index 0000000000..6406e1e25c
--- /dev/null
+++ b/frontend/src/container/FormAlertChannels/Settings/Telegram.tsx
@@ -0,0 +1,174 @@
+import { useTranslation } from 'react-i18next';
+import { Controller, useFormContext } from 'react-hook-form';
+import { Input } from '@signozhq/ui/input';
+import { Switch } from '@signozhq/ui/switch';
+import { Typography } from '@signozhq/ui/typography';
+import { Input as AntdInput } from 'antd';
+
+import { ChannelSpecFormValues } from '../../CreateAlertChannels/types';
+import FormCard from '../FormCard';
+import FormField from '../FormField';
+
+const { TextArea } = AntdInput;
+
+/**
+ * The API models the chat and the topic as integers. An empty or half-typed box
+ * has to become `undefined`, not `NaN`: `omitBlank` keeps `NaN`, which
+ * serialises as `null` and the API rejects it. react-hook-form also runs this
+ * over the value already in the form, which arrives as a number, not a string.
+ */
+const asOptionalNumber = (value: unknown): number | undefined => {
+ if (typeof value === 'number') {
+ return Number.isNaN(value) ? undefined : value;
+ }
+
+ if (typeof value !== 'string' || value.trim() === '') {
+ return undefined;
+ }
+
+ const parsed = Number(value);
+ return Number.isNaN(parsed) ? undefined : parsed;
+};
+
+function TelegramSettings(): JSX.Element {
+ const { t } = useTranslation('channels');
+ const {
+ register,
+ control,
+ formState: { errors },
+ } = useFormContext<ChannelSpecFormValues>();
+
+ return (
+ <>
+ <FormCard title={t('section_connection')}>
+ <Typography.Text
+ color="muted"
+ size="sm"
+ testId="telegram-tip"
+ style={{ display: 'block', marginBottom: 16 }}
+ >
+ {t('telegram_tip')}{' '}
+ <Typography.Link
+ href="https://core.telegram.org/bots#how-do-i-create-a-bot"
+ target="_blank"
+ rel="noopener noreferrer"
+ >
+ {t('telegram_tip_link')}
+ </Typography.Link>
+ </Typography.Text>
+
+ <FormField
+ label={t('field_telegram_bot_token')}
+ tooltip={t('tooltip_telegram_bot_token')}
+ error={errors.botToken?.message}
+ required
+ >
+ <Input
+ {...register('botToken')}
+ aria-required
+ type="password"
+ data-testid="telegram-bot-token-textbox"
+ />
+ </FormField>
+
+ <FormField
+ label={t('field_telegram_chat_id')}
+ tooltip={t('tooltip_telegram_chat_id')}
+ error={errors.chatId?.message}
+ required
+ >
+ <Input
+ {...register('chatId', { setValueAs: asOptionalNumber })}
+ aria-required
+ type="number"
+ placeholder={t('placeholder_telegram_chat_id')}
+ data-testid="telegram-chat-id-textbox"
+ />
+ </FormField>
+
+ <FormField
+ label={t('field_telegram_message_thread_id')}
+ tooltip={t('tooltip_telegram_message_thread_id')}
+ error={errors.messageThreadId?.message}
+ >
+ <Input
+ {...register('messageThreadId', { setValueAs: asOptionalNumber })}
+ type="number"
+ data-testid="telegram-message-thread-id-textbox"
+ />
+ </FormField>
+ </FormCard>
+
+ <FormCard title={t('section_message')}>
+ <FormField
+ label={t('field_telegram_title')}
+ tooltip={t('tooltip_telegram_title')}
+ error={errors.title?.message}
+ >
+ <Controller
+ control={control}
+ name="title"
+ render={({ field }): JSX.Element => (
+ <TextArea
+ rows={2}
+ data-testid="telegram-title-textarea"
+ value={(field.value as string) ?? ''}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ </FormField>
+
+ <FormField
+ label={t('field_telegram_message')}
+ tooltip={t('tooltip_telegram_message')}
+ error={errors.message?.message}
+ >
+ <Controller
+ control={control}
+ name="message"
+ render={({ field }): JSX.Element => (
+ <TextArea
+ rows={6}
+ data-testid="telegram-message-textarea"
+ value={(field.value as string) ?? ''}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ </FormField>
+ </FormCard>
+
+ <FormCard title={t('section_advanced')}>
+ <FormField
+ label={t('field_telegram_api_url')}
+ tooltip={t('tooltip_telegram_api_url')}
+ error={errors.apiUrl?.message}
+ >
+ <Input {...register('apiUrl')} data-testid="telegram-api-url-textbox" />
+ </FormField>
+
+ <FormField
+ label={t('field_telegram_disable_notifications')}
+ tooltip={t('tooltip_telegram_disable_notifications')}
+ >
+ <Controller
+ control={control}
+ name="disableNotifications"
+ render={({ field }): JSX.Element => (
+ <Switch
+ color="primary"
+ textPlacement="right"
+ testId="telegram-disable-notifications-switch"
+ value={!!field.value}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ </FormField>
+ </FormCard>
+ </>
+ );
+}
+
+export default TelegramSettings;
diff --git a/frontend/src/container/FormAlertChannels/index.tsx b/frontend/src/container/FormAlertChannels/index.tsx
index a100f530f7..46a7386f9f 100644
--- a/frontend/src/container/FormAlertChannels/index.tsx
+++ b/frontend/src/container/FormAlertChannels/index.tsx
@@ -20,6 +20,7 @@ import MsTeamsSettings from './Settings/MsTeams';
import OpsgenieSettings from './Settings/Opsgenie';
import PagerSettings from './Settings/Pager';
import SlackSettings from './Settings/Slack';
+import TelegramSettings from './Settings/Telegram';
import WebhookSettings from './Settings/Webhook';
import { Button } from '@signozhq/ui/button';
@@ -38,6 +39,7 @@ const CHANNEL_TYPE_OPTIONS = [
{ value: ChannelKind.jira, label: 'Jira' },
{ value: ChannelKind.jsmops, label: 'Jira Service Management Ops' },
{ value: ChannelKind.incidentio, label: 'incident.io' },
+ { value: ChannelKind.telegram, label: 'Telegram' },
];
function FormAlertChannels({
@@ -80,6 +82,8 @@ function FormAlertChannels({
return <IncidentIOSettings />;
case ChannelKind.opsgenie:
return <OpsgenieSettings />;
+ case ChannelKind.telegram:
+ return <TelegramSettings />;
case ChannelKind.email:
return <EmailSettings />;
default:
diff --git a/frontend/src/pages/AlertList/ChannelsEdit/stories/ChannelsEdit.stories.tsx b/frontend/src/pages/AlertList/ChannelsEdit/stories/ChannelsEdit.stories.tsx
index f020d9c330..9dd8e2908a 100644
--- a/frontend/src/pages/AlertList/ChannelsEdit/stories/ChannelsEdit.stories.tsx
+++ b/frontend/src/pages/AlertList/ChannelsEdit/stories/ChannelsEdit.stories.tsx
@@ -178,3 +178,8 @@ export const JiraServiceManagementOps: Story = {
export const IncidentIO: Story = {
args: { channelType: 'incidentio' },
};
+
+/** A Telegram channel, with its bot token masked behind the password field. */
+export const Telegram: Story = {
+ args: { channelType: 'telegram' },
+};
diff --git a/frontend/src/pages/AlertList/ChannelsEdit/stories/authz/ChannelsEdit.authz.stories.tsx b/frontend/src/pages/AlertList/ChannelsEdit/stories/authz/ChannelsEdit.authz.stories.tsx
index 8df2fe35fb..41ef597ed2 100644
--- a/frontend/src/pages/AlertList/ChannelsEdit/stories/authz/ChannelsEdit.authz.stories.tsx
+++ b/frontend/src/pages/AlertList/ChannelsEdit/stories/authz/ChannelsEdit.authz.stories.tsx
@@ -1,5 +1,5 @@
import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect, within } from 'storybook/test';
+import { expect, userEvent, within } from 'storybook/test';
import { storyMocks } from '@/storybook/controls/defineStoryMocks';
import type { PageStoryArgs } from '@/storybook/runtime/resolveStory';
@@ -106,6 +106,39 @@ export const ReadOnly: Story = {
},
};
+/**
+ * The same denial on a Telegram channel. Its fields are the kind the form gained
+ * last, including the only toggle a settings panel renders, so this is where a
+ * gap in the gating would show first.
+ *
+ * The switch is checked by behaviour, not by an attribute: it is a button inside
+ * the disabled fieldset, so it carries no `disabled` of its own and an
+ * attribute check would pass whether or not the browser actually turned it off.
+ */
+export const TelegramReadOnly: Story = {
+ args: { channelType: 'telegram', revoked: [UPDATE, CREATE, DELETE] },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await expectDisabled(
+ await canvas.findByTestId(
+ 'telegram-bot-token-textbox',
+ undefined,
+ PAGE_LOAD,
+ ),
+ );
+ await expectDisabled(await canvas.findByTestId('telegram-chat-id-textbox'));
+ await expectDisabled(await canvas.findByTestId('telegram-message-textarea'));
+
+ const toggle = await canvas.findByTestId(
+ 'telegram-disable-notifications-switch',
+ );
+ const before = toggle.getAttribute('aria-checked');
+ await userEvent.click(toggle);
+ await expect(toggle.getAttribute('aria-checked')).toBe(before);
+ },
+};
+
/** No channel permission at all: the page is denied before the form exists. */
export const NoChannelAccess: Story = {
args: { revoked: NOTIFICATION_CHANNEL },
diff --git a/frontend/src/pages/AlertList/ChannelsNew/stories/ChannelsNew.stories.tsx b/frontend/src/pages/AlertList/ChannelsNew/stories/ChannelsNew.stories.tsx
index 3668c1dd1d..01201d2620 100644
--- a/frontend/src/pages/AlertList/ChannelsNew/stories/ChannelsNew.stories.tsx
+++ b/frontend/src/pages/AlertList/ChannelsNew/stories/ChannelsNew.stories.tsx
@@ -178,6 +178,38 @@ export const IncidentIO: Story = {
},
};
+/** The Telegram form: the bot token, the chat it posts to and the message. */
+export const Telegram: Story = {
+ play: async ({ canvasElement }): Promise<void> => {
+ await selectChannelType(canvasElement, /^Telegram$/);
+ },
+};
+
+/**
+ * Telegram's own required fields. The chat id is the form's first numeric field,
+ * and the API treats 0 as missing, so an empty box has to report the same error
+ * as a blank one rather than sending a zero.
+ */
+export const TelegramRequiredFields: Story = {
+ play: async ({ canvasElement }): Promise<void> => {
+ const canvas = within(canvasElement);
+
+ await selectChannelType(canvasElement, /^Telegram$/);
+ await userEvent.type(
+ await canvas.findByTestId('channel-name-textbox'),
+ 'alerts-telegram',
+ );
+ await userEvent.click(await canvas.findByTestId('save-channel-button'));
+
+ await screen.findByText(
+ 'Bot token is mandatory for creating a telegram channel',
+ );
+ await screen.findByText(
+ 'Chat ID is mandatory for creating a telegram channel',
+ );
+ },
+};
+
/**
* The fields the API rejects a save without are marked before anything is
* submitted, so a long form does not have to be guessed at.
diff --git a/frontend/src/pages/AlertList/NotificationChannels/__tests__/ChannelFormPrefill.test.tsx b/frontend/src/pages/AlertList/NotificationChannels/__tests__/ChannelFormPrefill.test.tsx
index 3628b4f74b..ff005327a2 100644
--- a/frontend/src/pages/AlertList/NotificationChannels/__tests__/ChannelFormPrefill.test.tsx
+++ b/frontend/src/pages/AlertList/NotificationChannels/__tests__/ChannelFormPrefill.test.tsx
@@ -10,7 +10,7 @@ const FIND = { timeout: 5000 };
interface PrefillCase {
kind: string;
spec: Record<string, unknown>;
- fields: [string, string][];
+ fields: [string, string | number][];
}
const CASES: PrefillCase[] = [
@@ -186,6 +186,25 @@ const CASES: PrefillCase[] = [
['incidentio-description-textarea', 'incident description'],
],
},
+ {
+ kind: 'telegram',
+ spec: {
+ botToken: '123456789:AA-token',
+ chatId: -1001234567890,
+ messageThreadId: 42,
+ title: 'telegram title',
+ message: 'telegram message',
+ apiUrl: 'https://api.telegram.org',
+ },
+ fields: [
+ ['telegram-bot-token-textbox', '123456789:AA-token'],
+ ['telegram-chat-id-textbox', -1001234567890],
+ ['telegram-message-thread-id-textbox', 42],
+ ['telegram-title-textarea', 'telegram title'],
+ ['telegram-message-textarea', 'telegram message'],
+ ['telegram-api-url-textbox', 'https://api.telegram.org'],
+ ],
+ },
];
describe('ChannelForm prefill', () => {
diff --git a/frontend/src/pages/AlertList/stories/__story_mockdata__/alerts.ts b/frontend/src/pages/AlertList/stories/__story_mockdata__/alerts.ts
index e48f4a5725..bea101856b 100644
--- a/frontend/src/pages/AlertList/stories/__story_mockdata__/alerts.ts
+++ b/frontend/src/pages/AlertList/stories/__story_mockdata__/alerts.ts
@@ -81,6 +81,7 @@ export const CHANNEL_TYPES = [
'jira',
'jsmops',
'incidentio',
+ 'telegram',
] as const;
export type ChannelType = (typeof CHANNEL_TYPES)[number];
@@ -847,6 +848,13 @@ const CHANNEL_SPECS: Record<ChannelType, Record<string, unknown>> = {
title: '{{ .CommonLabels.alertname }}',
sendResolved: true,
},
+ telegram: {
+ botToken: '123456789:AA-story-telegram-token',
+ chatId: -1001234567890,
+ title: '{{ .CommonLabels.alertname }}',
+ message: '{{ range .Alerts -}}{{ .Annotations.description }}\n{{ end }}',
+ sendResolved: true,
+ },
};
/** The v2 fetch by id, which is what the redesigned screens read. */