Zulip Connector

Index streams, topics, and messages in Zulip.

The Zulip connector indexes content from your Zulip organization using Zulip API credentials.

Atolio recommends using a dedicated Zulip bot for this connector rather than a personal user account.

Create Zulip credentials

Create credentials for either:

  • a generic bot (recommended), or
  • a dedicated service user.

You can retrieve Zulip API credentials using Zulip’s API key documentation: https://zulip.com/api/api-keys.

When creating the account used by Atolio:

  • Use a dedicated bot or service account such as atolio-bot or atolio-export-bot.
  • Record the account email address.
  • Record the account API key.
  • Record your Zulip organization URL (for example, https://example.zulipchat.com).

Visibility and access

The Zulip connector can only index content visible to the configured bot or user:

  • Public streams are indexed.
  • Private streams are indexed only if the configured bot or user has been added to them.
  • Private messages (DMs) are not indexed by default but can be enabled per-user (see Index Private Messages below).

Because of this, Atolio recommends using a dedicated generic bot with the appropriate stream access.

Provide Configuration

Provide the following values to your Deployment Engineer:

  • Domain: your Zulip organization URL (for example, https://example.zulipchat.com)
  • Email: the email address of the Zulip bot or service user
  • Token: the Zulip API key for that bot or user

Content Filtering

The Zulip connector supports filtering at the topic resource level.

Topics can be included or excluded using the format:

resources:
  topic:
    excluded:
      - engineering/Incident review

Each entry should be specified as:

  • stream/topic

For example:

resources:
  topic:
    excluded:
      - eng-general/Search Results Feedback (query)

If you need topic-level filtering, provide the inclusions or exclusions to your Deployment Engineer as part of the connector configuration.

Index Private Messages

By default, the Zulip connector does not index private messages (DMs). To enable DM indexing, each user who wants their private messages indexed must provide a personal Zulip API key.

Unlike Slack, Zulip does not currently support an OAuth-based authentication flow for this purpose. Each user must retrieve their API key manually and share it securely with their Atolio deployment administrator.

Retrieve your Zulip API key

Each user should follow these steps:

  1. In Zulip, open the Settings menu (gear icon in the top right).
  2. Navigate to Personal Settings → Account & privacy.
  3. Click Manage your API key at the bottom of the page. Your API key will be displayed — copy it.

Warning: Your Zulip API key grants full access to your Zulip account. Share it only through a secure channel (for example, a password manager or encrypted message). Do not share it over Zulip, Slack, email, or other unencrypted channels.

  1. Share the API key securely with your Atolio deployment administrator.

Configure user tokens

Once user API keys have been collected, provide them to your Deployment Engineer. They are stored in the connector configuration as a user_tokens secret, mapping each user’s Zulip email address to their API key:

secrets:
  user_tokens:
    value: |
      "alice@example.com": "abc123XXXX"
      "bob@example.com": "def456XXXX"

After the configuration is updated, private messages for those users will be indexed on the next sync.