Skip to content

Zulip Chat

Zulip is an open-source group chat application that supports both live and asynchronous conversations. Shoutrrr's Zulip service sends notifications to Zulip streams using bot credentials.

URL Format

zulip://botmail:botkey@host/?stream=stream&topic=topic

URL Fields

  • BotMail - Bot e-mail address (Required)
    URL part: zulip://botmail:botkey@host/
  • BotKey - API key (Required)
    URL part: zulip://botmail:botkey@host/
  • Host - API server hostname (with optional port) (Required)
    URL part: zulip://botmail:botkey@host/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • read_by_sender - Mark the message read by its sender Default: ❌ No

  • stream - Target stream name Default: empty

  • title - Notification title prepended to message Default: empty

  • to - Comma-separated user IDs or emails for DMs Default: empty

  • topic - Stream topic Default: empty

  • type - Message type (channel or direct) Default: empty

Note

When constructing the service URL manually, the @ in the bot e-mail address must be URL-encoded as %40. When using the Go API or the playground, this is handled automatically.

Note

The host field may include a non-standard port (e.g., zulip.example.com:8443). When using the default HTTPS port (443), the port can be omitted.

Bot Setup

To use Shoutrrr with Zulip, you need to create a bot in your Zulip organization:

  1. Go to Settings → Personal settings → Bots
  2. Click Add a new bot
  3. Choose Generic bot as the bot type
  4. Fill in the bot name and optionally an avatar
  5. Click Create bot
  6. Copy the bot's email and API key

Use the bot email as the botmail and the API key as the botkey in your service URL.

Stream and Topic

Both stream and topic are optional. They can be provided in the service URL or overridden at send time using types.Params:

  • Stream: The name of the Zulip stream to send messages to (e.g., general, alerts)
  • Topic: The message topic within the stream (e.g., server-monitoring). Zulip topics keep conversations organized within a stream.
  • Title: A notification title that is prepended to the message content. If no topic is set, the title is used as the topic instead.

If neither is specified, the message is sent to the default stream configured for the bot.

Examples

Basic notification (default stream)

zulip://my-bot%40zulipchat.com:[email protected]

With stream and topic in URL

zulip://my-bot%40zulipchat.com:[email protected]?stream=alerts&topic=monitoring

With custom port

zulip://my-bot%40zulipchat.com:[email protected]:8443?stream=general

Override stream and topic at send time

sender, _ := shoutrrr.CreateSender(url)

params := make(types.Params)
params["stream"] = "alerts"
params["topic"] = "disk-space-warning"

sender.Send("Disk usage exceeded 90% on server-01", &params)

Add a notification title to the message

params := make(types.Params)
params["title"] = "Deployment Notification"

sender.Send("Deployed v2.3.1 to production", &params)

Override topic at send time

params := make(types.Params)
params["topic"] = "deployment-notification"

sender.Send("Deployed v2.3.1 to production", &params)

Using the CLI

shoutrrr send --url "zulip://bot%40example.com:[email protected]?stream=alerts" --message "Server restarted"

Direct Messages

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).

Direct message via params

params := make(types.Params)
params["type"] = "direct"
params["to"] = "[email protected],[email protected]"

sender.Send("Hello via DM", &params)

Direct message service URL

zulip://my-bot%40zulipchat.com:[email protected]?type=direct&[email protected],[email protected]

Server-Side Limits

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.