Debian Codegraph @

pkg/services/chat/lark/doc.go

raw
1 // Package lark provides a service for sending notifications to Lark (Feishu) via webhooks.
2 //
3 // The Lark service supports webhook integration for sending text and rich post messages
4 // to Lark or Feishu platforms using their Bot API.
5 //
6 // # URL Format
7 //
8 // The service URL follows the format:
9 //
10 // lark://host/token?secret=SECRET&title=TITLE
11 //
12 // Where:
13 // - host: The API host, either "open.larksuite.com" (Lark) or "open.feishu.cn" (Feishu)
14 // - token: The webhook token from the bot configuration
15 // - secret: Optional signing secret for request verification
16 // - title: Optional message title for rich post messages
17 //
18 // # Basic Usage
19 //
20 // import "github.com/nicholas-fedor/shoutrrr/pkg/services/chat/lark"
21 //
22 // service := &lark.Service{}
23 // err := service.Initialize(url, logger)
24 // if err != nil {
25 // // handle error
26 // }
27 // err = service.Send("Hello, Lark!", nil)
28 //
29 // # Configuration Options
30 //
31 // The service supports configuration via URL components:
32 //
33 // - Host: The API host (default: "open.larksuite.com", or "open.feishu.cn")
34 // - Path: The webhook token (required)
35 // - Secret: Optional signing secret for request verification (query parameter)
36 // - Title: Optional message title for rich post messages (query parameter)
37 // - Link: Optional URL link to include in post messages (query parameter)
38 //
39 // # Message Types
40 //
41 // The service supports two message types:
42 //
43 // - Text: Simple text messages sent when no title is provided
44 // - Post: Rich formatted messages with title and optional link when title is provided
45 //
46 // # Obtaining Webhook Credentials
47 //
48 // To obtain the webhook URL and credentials:
49 //
50 // 1. Open your Lark/Feishu group chat
51 // 2. Click "Settings" → "Group Settings" → "Bots"
52 // 3. Add a custom bot
53 // 4. Copy the webhook URL and optionally enable signature verification
54 // 5. Extract the token from the webhook URL path
55 //
56 // # Important Notes
57 //
58 // - The service requires a valid host and token for authentication
59 // - Messages have a maximum length of 4096 bytes
60 // - Signature verification requires the secret to be configured
61 // - Supports both Lark (open.larksuite.com) and Feishu (open.feishu.cn) platforms
62 // - Rich post messages require a title to be specified
63 // - Link parameter is only used when title is provided for post messages
64 package lark