snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

api_docs/zulip-urls.md

@@ -0,0 +1,109 @@
+# Zulip URLs
+
+This page details how to properly construct and parse the URLs that
+the Zulip web app uses for various types of views.
+
+Because other clients needs to be able to resolve and process these
+links in order to implement equivalent behavior that navigates
+directly in say the mobile apps, it's important to have a clear
+specification of exactly how these URLs work.
+
+Essentially all of the data is encoded in the URL fragment (`#`) part
+of a URL; the protocol, host and path will just be the canonical URL
+for the Zulip server (In these examples,
+`https://zulip.example.com/`).
+
+## Message feed views
+
+Most links in Zulip are to message feed views, and for that reason
+these have the most developed syntax and legacy behavior.
+
+Message feed URLs always start with `#narrow/`, follow by one or more
+[search operator/operand pairs](/api/construct-narrow), separated by
+`/`s. The operator may be negated by putting a `-` at the start of
+it. For example:
+
+`https://zulip.example.com/#narrow/is/starred/sender/17/-channel/14`
+
+is the feed of starred messages sent by user ID to everywhere but
+channel 14. The search documentation covers the valid operators and
+their meaning.
+
+See also the relevant [message formatting
+documentation](/api/message-formatting) for details on Markdown
+representations of Zulip-internal links that will be translated into
+HTML containing links that use these URLs.
+
+Here, we describe some special encoding rules.
+
+### Operand encoding and decoding
+
+Strings in operands are URL-encoded, and then additional substitution
+rules are applied to avoid over-zealous browser handling of certain
+characters in the URL fragment:
+
+- `%` => `.`
+- `(` => `.28`
+- `)` => `.29`
+- `.` => `.2E`
+
+They can decoded by applying the reverse transformation: Replace all
+`.` characters with `%`, and then do standard URL-decoding.
+
+### Encoding channels
+
+Channel operands must be encoded in one of the two modern fully
+supported formats:
+
+- `42`: Just the ID of the channel. Clients should simply parse the
+  channel ID to look up the channel, which is of course not guaranteed
+  to be accessible to the acting user or even exist.
+- `42-channel-name`. The ID of the channel, with a human-readable hint
+  of the channel name. Clients generating Zulip URLs are recommended
+  to include channel name hints where there is a readable URL-encoding
+  of the channel name, but to skip doing so for channel names written
+  in non-ascii languages or where otherwise the slug would not make
+  the URL nicer for humans. Clients must parse this format by
+  discarding everything after the `-` and treating it identically to
+  the simpler integer-only format. Note that means nothing enforces
+  that the string have anything to do with the channel name;
+  functionally, it just an optional hint.
+
+These two formats allow Zulip URLs to stably refer to a specific
+channel, even though channels can be renamed, while still allowing the
+URLs to have user-friendly name hints most of the time.
+
+There is an additional legacy format that was used prior to 2018 that
+clients are required to support:
+
+- `channel-name`: Legacy format of just the channel name, URL-encoded
+  and with spaces replaced with dashes. The legacy format should never
+  take precedence over the modern format, so a link with
+  `2016-election` as the slug must be parsed as the channel with ID
+  2016, even if theoretically it could have been originally intended
+  as referring to a channel named `2016 election`.
+
+Clients are not recommended to ever generate this legacy format.
+
+## zulip:// links for mobile login
+
+Zulip's single-sign on login process for the mobile app ends with a
+redirect to `zulip://login` with the following query parameters:
+
+- `email`: The email address for the authenticated account.
+- `otp_encrypted_api_key`: The API key for the client, encrypted using
+  the `mobile_flow_otp` that the client provided when initiating the
+  login attempt.
+- `realm`: The full URL of the Zulip organization.
+- `user_id`: The Zulip user ID for the authenticated account.
+
+**Changes**: The `user_id` field was added to the set of included
+query parameters in Zulip 5.0 (feature level 128).
+
+## Related articles
+
+* [Message formatting API](/api/message-formatting)
+* [Construct a narrow](/api/construct-narrow) for search.
+* [Markdown formatting help](/help/format-your-message-using-markdown)
+* [Send a message](/api/send-message)
+