Debian Codegraph @

pkg/services/chat/telegram/doc.go

raw
1 // Package telegram provides a notification service for sending messages to Telegram chats.
2 //
3 // This package is part of the shoutrrr notification library and implements the Service interface
4 // for delivering notifications to Telegram chats using the Telegram Bot API.
5 //
6 // # Service Configuration
7 //
8 // The Service struct provides the main functionality for sending notifications to Telegram.
9 // It embeds standard.Standard for common service features and supports sending messages
10 // to multiple chat IDs with customizable formatting options.
11 //
12 // # Configuration Fields
13 //
14 // The Config struct supports the following settings:
15 //
16 // - Token: The Telegram bot token in the format "botID:token" (required)
17 // - Chats: List of chat IDs or channel names to send messages to (required)
18 // - Preview: Enable/disable web page preview for URLs (optional, default: true)
19 // - Notification: Enable/disable notification sound (optional, default: true)
20 // - ParseMode: How to parse the message text (None, Markdown, HTML, MarkdownV2) (optional, default: None)
21 // - Title: Notification title prepended to messages (optional)
22 //
23 // # Parse Modes
24 //
25 // The package supports multiple text parsing modes:
26 //
27 // - None: Plain text without formatting
28 // - Markdown: Classic Markdown formatting
29 // - HTML: HTML tag-based formatting
30 // - MarkdownV2: Extended Markdown formatting
31 //
32 // # Usage Example
33 //
34 // service := &telegram.Service{}
35 // err := service.Initialize(serviceURL, logger)
36 // if err != nil {
37 // // handle error
38 // }
39 // err = service.Send("Your message here", nil)
40 //
41 // # JSON Payload Creation
42 //
43 // The package provides createSendMessagePayload for building properly formatted Telegram
44 // Bot API payloads with support for message text, parse modes, notifications, and previews.
45 //
46 // # URL Format
47 //
48 // The configuration URL format is:
49 //
50 // telegram://botID:token@telegram/?chats=@channel1,@channel2&parsemode=HTML
51 //
52 // # Interactive Setup
53 //
54 // The package includes a generator for interactive configuration setup, allowing users
55 // to configure the service through a guided process.
56 //
57 // For more information about Telegram bots, visit: https://core.telegram.org/bots
58 package telegram