Debian Codegraph @

docs/services/chat/zulip/index.md

raw
1 # Zulip Chat
2
3 [Zulip](https://zulip.com/) is an open-source group chat application that supports both live and asynchronous conversations.
4 Shoutrrr's Zulip service sends notifications to Zulip streams using bot credentials.
5
6 ## URL Format
7
8 !!! info ""
9 zulip://__`botmail`__:__`botkey`__@__`host`__/?stream=__`stream`__&topic=__`topic`__
10
11 --8<-- "docs/services/chat/zulip/config.md"
12
13 !!! note
14 When constructing the service URL manually, the `@` in the bot e-mail address must be
15 URL-encoded as `%40`. When using the Go API or the playground, this is handled automatically.
16
17 !!! note
18 The __`host`__ field may include a non-standard port (e.g., `zulip.example.com:8443`).
19 When using the default HTTPS port (443), the port can be omitted.
20
21 ## Bot Setup
22
23 To use Shoutrrr with Zulip, you need to create a bot in your Zulip organization:
24
25 1. Go to __Settings__ → __Personal settings__ → __Bots__
26 2. Click __Add a new bot__
27 3. Choose __Generic bot__ as the bot type
28 4. Fill in the bot name and optionally an avatar
29 5. Click __Create bot__
30 6. Copy the bot's __email__ and __API key__
31
32 Use the bot email as the `botmail` and the API key as the `botkey` in your service URL.
33
34 ## Stream and Topic
35
36 Both `stream` and `topic` are optional. They can be provided in the service URL or overridden
37 at send time using `types.Params`:
38
39 - __Stream__: The name of the Zulip stream to send messages to (e.g., `general`, `alerts`)
40 - __Topic__: The message topic within the stream (e.g., `server-monitoring`). Zulip topics keep
41 conversations organized within a stream.
42 - __Title__: A notification title that is prepended to the message content. If no `topic` is
43 set, the `title` is used as the topic instead.
44
45 If neither is specified, the message is sent to the default stream configured for the bot.
46
47 ## Examples
48
49 !!! example "Basic notification (default stream)"
50 ```uri
51 zulip://my-bot%40zulipchat.com:[email protected]
52 ```
53
54 !!! example "With stream and topic in URL"
55 ```uri
56 zulip://my-bot%40zulipchat.com:[email protected]?stream=alerts&topic=monitoring
57 ```
58
59 !!! example "With custom port"
60 ```uri
61 zulip://my-bot%40zulipchat.com:[email protected]:8443?stream=general
62 ```
63
64 !!! example "Override stream and topic at send time"
65 ```go
66 sender, _ := shoutrrr.CreateSender(url)
67
68 params := make(types.Params)
69 params["stream"] = "alerts"
70 params["topic"] = "disk-space-warning"
71
72 sender.Send("Disk usage exceeded 90% on server-01", &params)
73 ```
74
75 !!! example "Add a notification title to the message"
76 ```go
77 params := make(types.Params)
78 params["title"] = "Deployment Notification"
79
80 sender.Send("Deployed v2.3.1 to production", &params)
81 ```
82
83 !!! example "Override topic at send time"
84 ```go
85 params := make(types.Params)
86 params["topic"] = "deployment-notification"
87
88 sender.Send("Deployed v2.3.1 to production", &params)
89 ```
90
91 !!! example "Using the CLI"
92 ```bash
93 shoutrrr send --url "zulip://bot%40example.com:[email protected]?stream=alerts" --message "Server restarted"
94 ```
95
96 ## Direct Messages
97
98 To send a direct message, set the `type` parameter to `direct` and provide recipients via the `to` parameter (comma-separated emails or user IDs). The `stream` value can serve as a fallback recipient list for direct messages. The `topic` parameter is ignored for direct messages (only channels use topics).
99
100 !!! example "Direct message via params"
101 ```go
102 params := make(types.Params)
103 params["type"] = "direct"
104 params["to"] = "[email protected],[email protected]"
105
106 sender.Send("Hello via DM", &params)
107 ```
108
109 !!! example "Direct message service URL"
110 ```
111 zulip://my-bot%40zulipchat.com:[email protected]?type=direct&[email protected],[email protected]
112 ```
113
114 ## Server-Side Limits
115
116 The service fetches `max_message_length` and `max_topic_length` from Zulip's register endpoint on the first send (with 10s timeout). If the request fails or returns zero values, it falls back to 10,000 bytes for content and 60 characters for topics. Length checks use rune count for topics (Unicode aware) and byte count for message content.