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.

Required Configuration Values

Enter these values in the Atolio Admin console (v4.24 and later), or send them to Atolio Support (your Deployment Engineer).

Value	Where to find it	Example / format	Secret
Organization URL	`Create Zulip credentials`, your Zulip organization URL	`https://example.zulipchat.com`	No
Bot or service user email	`Create Zulip credentials`, the account’s email address	`atolio-bot@example.zulipchat.com`	No
API key	`Create Zulip credentials`, the API key of that bot or user	Long random string	Yes
Per-user API keys (only if indexing private messages)	Index Private Messages, one personal API key per user, mapped to their Zulip email	`"alice@example.com": "<api-key>"`	Yes

Keep secrets secure: Share values marked “Yes” in the Secret column only through a password-manager share (e.g. 1Password) or another secure channel agreed with Atolio Support. Never send them in plain email, chat, or support tickets.

Configuration Example

Add this block to connector-values.yaml. Replace each <PLACEHOLDER> with the matching value from the table above, and remove any line marked “Only if” that doesn’t apply.

connectors:
  zulip:
    default:
      zulip:
        connector: zulip
        instance: default
        source: zulip
        common:
          enabled: true
          identity-provider: false
          cron-spec: "0 7 * * *"  # Zulip is only synced on this schedule
        secrets:
          token:
            value: "<API_KEY>"
          user_tokens:  # Only if indexing private messages
            value: |
              "<USER_EMAIL>": "<USER_API_KEY>"
        configuration:
          domain: "<ORGANIZATION_URL>"
          email: "<BOT_OR_SERVICE_USER_EMAIL>"

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 the admin configuring Atolio, who includes it with the Required Configuration Values.

Retrieve your Zulip API key

Each user should follow these steps:

In Zulip, open the Settings menu (gear icon in the top right).
Navigate to Personal Settings → Account & privacy.
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.

Share the API key securely with the admin configuring Atolio, who includes it with the Required Configuration Values.

Configure user tokens

Once user API keys have been collected, provide them as described in Required Configuration Values. 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.