Skip to content

The only tool you need to know what is happening and how to fix it.

telegram added (#157)

narrow-adventuredc84a53d236b
diff --git a/README.md b/README.md
index cb1cc2ad..2b7f2e90 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ Traceway is an **OpenTelemetry-native** observability platform that combines **l
- **Session Replay** — Watch what the user did right before the error. Available for web (any JS framework) and Flutter.
- **AI Observability** — LLM cost, tokens, latency, and full conversations across providers (OpenRouter and any OTel-compatible AI gateway).
-Plus: configurable alerts (Slack / GitHub / email / webhook / Pushover), Apdex + Impact-Score endpoint ranking, multi-tenant orgs with role-based access, and a per-endpoint slow-threshold override.
+Plus: configurable alerts (Slack / GitHub / email / webhook / Pushover / Telegram), Apdex + Impact-Score endpoint ranking, multi-tenant orgs with role-based access, and a per-endpoint slow-threshold override.
## Why Traceway
diff --git a/backend/app/controllers/notification_channel.controller.go b/backend/app/controllers/notification_channel.controller.go
index 38678686..38e92961 100644
--- a/backend/app/controllers/notification_channel.controller.go
+++ b/backend/app/controllers/notification_channel.controller.go
@@ -43,7 +43,7 @@ type createChannelRequest struct {
}
var validChannelTypes = map[string]bool{
- "email": true, "webhook": true, "slack": true, "github": true, "pushover": true,
+ "email": true, "webhook": true, "slack": true, "github": true, "pushover": true, "telegram": true,
}
func (ctrl *notificationChannelController) Create(ctx *gin.Context) {
@@ -69,7 +69,7 @@ func (ctrl *notificationChannelController) Create(ctx *gin.Context) {
return
}
if !validChannelTypes[req.ChannelType] {
- ctx.JSON(http.StatusUnprocessableEntity, gin.H{"error": "Channel type must be one of: email, webhook, slack, github, pushover."})
+ ctx.JSON(http.StatusUnprocessableEntity, gin.H{"error": "Channel type must be one of: email, webhook, slack, github, pushover, telegram."})
return
}
@@ -142,7 +142,7 @@ func (ctrl *notificationChannelController) Update(ctx *gin.Context) {
return
}
if !validChannelTypes[req.ChannelType] {
- ctx.JSON(http.StatusUnprocessableEntity, gin.H{"error": "Channel type must be one of: email, webhook, slack, github, pushover."})
+ ctx.JSON(http.StatusUnprocessableEntity, gin.H{"error": "Channel type must be one of: email, webhook, slack, github, pushover, telegram."})
return
}
diff --git a/backend/app/notifications/adapter_telegram.go b/backend/app/notifications/adapter_telegram.go
new file mode 100644
index 00000000..ce5daa2d
--- /dev/null
+++ b/backend/app/notifications/adapter_telegram.go
@@ -0,0 +1,92 @@
+package notifications
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "regexp"
+ "strings"
+ "time"
+)
+
+type TelegramAdapter struct {
+ BotToken string `json:"botToken"`
+ ChatId string `json:"chatId"`
+}
+
+var telegramBotTokenRe = regexp.MustCompile(`^\d+:[A-Za-z0-9_-]+$`)
+
+func (a *TelegramAdapter) Type() string { return "telegram" }
+
+func (a *TelegramAdapter) Validate() error {
+ token := strings.TrimSpace(a.BotToken)
+ if token == "" {
+ return fmt.Errorf("Telegram bot token is required")
+ }
+ if !telegramBotTokenRe.MatchString(token) {
+ return fmt.Errorf("Telegram bot token format looks invalid (expected '<id>:<secret>')")
+ }
+ if strings.TrimSpace(a.ChatId) == "" {
+ return fmt.Errorf("Telegram chat ID is required")
+ }
+ return nil
+}
+
+func (a *TelegramAdapter) Send(ctx context.Context, msg Message) error {
+ var text strings.Builder
+ if msg.Subject != "" {
+ text.WriteString(msg.Subject)
+ text.WriteString("\n\n")
+ }
+ text.WriteString(msg.Body)
+ if msg.URL != "" {
+ text.WriteString("\n\n")
+ text.WriteString(msg.URL)
+ }
+
+ form := url.Values{
+ "chat_id": {a.ChatId},
+ "text": {text.String()},
+ "disable_web_page_preview": {"true"},
+ }
+
+ endpoint := fmt.Sprintf("https://api.telegram.org/bot%s/sendMessage", url.PathEscape(strings.TrimSpace(a.BotToken)))
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
+ if err != nil {
+ return fmt.Errorf("failed to create Telegram request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+ client := &http.Client{Timeout: 10 * time.Second}
+ resp, err := client.Do(req)
+ if err != nil {
+ return fmt.Errorf("Telegram request failed: %w", err)
+ }
+ defer resp.Body.Close()
+
+ respBody, _ := io.ReadAll(resp.Body)
+
+ if resp.StatusCode == http.StatusOK {
+ var result struct {
+ Ok bool `json:"ok"`
+ }
+ if err := json.Unmarshal(respBody, &result); err == nil && result.Ok {
+ return nil
+ }
+ return fmt.Errorf("Telegram returned unexpected response: %s", string(respBody))
+ }
+
+ var errResult struct {
+ Ok bool `json:"ok"`
+ ErrorCode int `json:"error_code"`
+ Description string `json:"description"`
+ }
+ if err := json.Unmarshal(respBody, &errResult); err == nil && errResult.Description != "" {
+ return fmt.Errorf("Telegram returned %d: %s", resp.StatusCode, errResult.Description)
+ }
+
+ return fmt.Errorf("Telegram returned status %d", resp.StatusCode)
+}
diff --git a/backend/app/notifications/adapters.go b/backend/app/notifications/adapters.go
index c44700ff..966d2158 100644
--- a/backend/app/notifications/adapters.go
+++ b/backend/app/notifications/adapters.go
@@ -63,6 +63,12 @@ func NewAdapter(channelType string, configJSON json.RawMessage) (Adapter, error)
return nil, fmt.Errorf("invalid pushover config: %w", err)
}
return &cfg, nil
+ case "telegram":
+ var cfg TelegramAdapter
+ if err := json.Unmarshal(configJSON, &cfg); err != nil {
+ return nil, fmt.Errorf("invalid telegram config: %w", err)
+ }
+ return &cfg, nil
default:
return nil, fmt.Errorf("unknown channel type: %s", channelType)
}
diff --git a/docs/pages/learn/alerts.mdx b/docs/pages/learn/alerts.mdx
index 80bbb690..495df4f8 100644
--- a/docs/pages/learn/alerts.mdx
+++ b/docs/pages/learn/alerts.mdx
@@ -1,19 +1,19 @@
# Alerts
-Alerts notify you when conditions in your application require attention — errors, latency spikes, metric thresholds, or missing data. Configure channels and rules to get notified through email, Slack, webhooks, GitHub Issues, or Pushover.
+Alerts notify you when conditions in your application require attention — errors, latency spikes, metric thresholds, or missing data. Configure channels and rules to get notified through email, Slack, webhooks, GitHub Issues, Pushover, or Telegram.
## How Alerts Work
The alerting system has two parts:
-- **Channels** define where notifications are delivered (email, Slack, webhook, GitHub, Pushover)
+- **Channels** define where notifications are delivered (email, Slack, webhook, GitHub, Pushover, Telegram)
- **Rules** define what conditions trigger a notification
When a rule's condition is met, Traceway sends a notification through the rule's attached channel. Each rule is linked to exactly one channel, but a channel can be used by multiple rules.
## Channels
-A channel represents a notification destination. Traceway supports four channel types:
+A channel represents a notification destination. Traceway supports the following channel types:
| Channel | Description | Configuration |
|---------|-------------|---------------|
@@ -22,6 +22,7 @@ A channel represents a notification destination. Traceway supports four channel
| Webhook | Sends an HTTP POST with a JSON payload to any URL | URL, optional headers, optional HMAC secret |
| GitHub | Creates a GitHub issue in a repository | Personal access token, repository owner/name, optional labels |
| Pushover | Sends push notifications to your mobile devices | User Key, App Token |
+| Telegram | Sends a message via a Telegram bot to a user or group chat | Bot Token, Chat ID |
Each channel has a **Test** button that sends a sample notification so you can verify the configuration before attaching rules.
@@ -74,6 +75,25 @@ Then configure the GitHub channel in Traceway:
<img src="/channel-github.png" alt="GitHub channel configuration dialog" style={{ maxWidth: '100%', height: 'auto', marginTop: '16px', borderRadius: '8px', border: '1px solid #e5e7eb' }} />
+### Setting Up Telegram
+
+To send alerts to a Telegram user or group, you need a **Bot Token** and a **Chat ID**:
+
+1. Open Telegram and start a chat with [@BotFather](https://t.me/BotFather)
+2. Send `/newbot`, then follow the prompts to give your bot a name and username
+3. BotFather will reply with a **Bot Token** in the form `123456789:ABCdefGhIJKlmNoPQRstuVwxyZ` — copy it
+4. Decide where the bot should post:
+ - **Direct messages:** open a chat with your new bot and send it any message, then visit `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates` in a browser and copy the `chat.id` value from the response
+ - **Group chat:** add the bot to the group, send a message in the group, then visit the same `getUpdates` URL and copy the `chat.id` (group IDs are negative numbers, e.g. `-1001234567890`)
+5. Send a `/start` message to the bot at least once so it is allowed to message you
+
+Then configure the Telegram channel in Traceway:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Bot Token | Yes | The token BotFather gave you |
+| Chat ID | Yes | The destination user or group chat ID |
+
### Webhook Payload
When a webhook channel fires, Traceway sends a JSON POST request with the following fields:
diff --git a/frontend/src/routes/notifications/+page.svelte b/frontend/src/routes/notifications/+page.svelte
index 6e8b8cb5..7ba6f448 100644
--- a/frontend/src/routes/notifications/+page.svelte
+++ b/frontend/src/routes/notifications/+page.svelte
@@ -98,7 +98,8 @@
webhook: 'Webhook',
slack: 'Slack',
github: 'GitHub',
- pushover: 'Pushover'
+ pushover: 'Pushover',
+ telegram: 'Telegram'
};
const tabDescriptions: Record<string, string> = {
diff --git a/frontend/src/routes/notifications/channel-dialog.svelte b/frontend/src/routes/notifications/channel-dialog.svelte
index 38d78486..8dc55832 100644
--- a/frontend/src/routes/notifications/channel-dialog.svelte
+++ b/frontend/src/routes/notifications/channel-dialog.svelte
@@ -54,6 +54,8 @@
let pushoverSound = $state('');
let pushoverHtml = $state(false);
let pushoverTtl = $state(0);
+ let telegramBotToken = $state('');
+ let telegramChatId = $state('');
const isEditing = $derived(channel !== null);
@@ -62,7 +64,8 @@
{ value: 'webhook', label: 'Webhook' },
{ value: 'slack', label: 'Slack' },
{ value: 'github', label: 'GitHub' },
- { value: 'pushover', label: 'Pushover' }
+ { value: 'pushover', label: 'Pushover' },
+ { value: 'telegram', label: 'Telegram' }
];
function resetForm() {
@@ -91,6 +94,8 @@
pushoverSound = '';
pushoverHtml = false;
pushoverTtl = 0;
+ telegramBotToken = '';
+ telegramChatId = '';
}
function populateFromChannel(ch: NotificationChannel) {
@@ -130,6 +135,9 @@
pushoverSound = config.sound || '';
pushoverHtml = config.html ?? false;
pushoverTtl = config.ttl ?? 0;
+ } else if (ch.channelType === 'telegram') {
+ telegramBotToken = config.botToken || '';
+ telegramChatId = config.chatId || '';
}
}
@@ -179,6 +187,11 @@
if (pushoverHtml) config.html = pushoverHtml;
if (Number(pushoverTtl) > 0) config.ttl = Number(pushoverTtl);
return config;
+ } else if (channelType === 'telegram') {
+ return {
+ botToken: telegramBotToken,
+ chatId: telegramChatId
+ };
}
return {};
}
@@ -475,6 +488,26 @@
<Label for="po-ttl">Time to Live (seconds, 0 = forever)</Label>
<Input id="po-ttl" type="number" bind:value={pushoverTtl} min={0} placeholder="0" />
</div>
+ {:else if channelType === 'telegram'}
+ <div class="space-y-2">
+ <Label for="tg-bot-token">Bot Token</Label>
+ <Input
+ id="tg-bot-token"
+ type="password"
+ bind:value={telegramBotToken}
+ placeholder="Token from @BotFather"
+ required
+ />
+ </div>
+ <div class="space-y-2">
+ <Label for="tg-chat-id">Chat ID</Label>
+ <Input
+ id="tg-chat-id"
+ bind:value={telegramChatId}
+ placeholder="Destination user or group ID"
+ required
+ />
+ </div>
{/if}
{#if error}