Add a custom linkification filter

Note: This feature can only be controlled by organization administrators.

Linkification filters are used to automatically translate syntax referring to an issue or support ticket in a message into a link to that issue or ticket on a third-party site. For instance, you can define a filter to automatically linkify #1234 to https://github.com/zulip/zulip/pulls/1234, Z1234 to link to that Zendesk ticket ID, or anything similar.

  1. From your desktop, click on the gear () in the upper right corner.

  2. Select Manage organization.

  3. On the left, click Filter settings.

  4. In the green section labeled Add a new filter, find the Regular expression and URL format string fields.

    • In the Regular expression field, enter a regular expression that searches and identifies the phrases you want to linkify.

      For example, if you want to linkify any numeric phrase that begins with a #, you could use the regular expression #(?P<id>[0-9]+) to find those phrases, where id is the variable that represents the phrase found by the search.

      Please note that all regular expressions used for custom linkification filters in your organization must be unique. In addition, the regular expression you enter must have a variable that gets identified by the URL format string.

    • In the URL format string field, insert a URL that includes the regular expression variable you specified in the Regular expression field. The URL format string must be in the format of https://example.com/%(\w+)s.

      For example, if you want to use the variable id found by your regular expression to link to a corresponding GitHub pull request on the zulip/zulip repository, you could use the URL format string https://github.com/zulip/zulip/pull/%(id)s.

  5. After filling out the Regular expression and URL format string fields, click the Add filter button to add your custom linkification filter to your Zulip organization.

  6. Upon clicking the Add filter button, you will receive a notification labeled Custom filter added! in the Custom linkification filters section, confirming the success of the addition of your custom linkification filter to your organization.

    Custom linkification filter success

    The filter's information and settings will also be displayed above the Add a new filter section. You can choose to delete any custom linkification filters in your organization through this panel by pressing the Delete button next to the filter you want to delete.

  7. Users in your organization can now use your custom linkification filter in their messages.

    Custom linkification filter demo

  8. If the pattern appears in a message topic, Zulip can't linkify the text in the topic itself (since clicking a topic narrows to that topic), so Zulip instead provides a little button to the right of the topic that you can click to go to the appropriate URL.