Zulip

1. Overview

Zulip is a powerful, open-source team chat application that combines the immediacy of real-time chat with the productivity benefits of threaded conversations. It helps teams stay organized and efficient by allowing discussions to be categorized into specific topics within streams.

With the GoInsight Zulip node, you can seamlessly integrate your team's communication hub into your automated workflows. This allows you to manage core aspects of your Zulip organization programmatically, including:

• Message Management: Send messages to streams or users, and retrieve, update, or delete existing messages.
• Stream Administration: Create, list, update, and delete communication streams.
• User Provisioning: Automate the creation, retrieval, modification, and deactivation of user accounts.

2. Prerequisites

Before using this node, you need to have a valid Zulip account with access to a Zulip organization. You may also need administrative permissions to create a bot and obtain its API key, which is required for authentication.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides a comprehensive set of operations for managing Messages, Streams, and Users within your Zulip organization. The table below summarizes the available actions.

Operation Details

Create a Stream

Create a stream in Zulip.

Input Parameters:

• StreamName: Name of the stream to create.

Options:

• Description: Description of the stream.

Output:

• Stream (object): ID of the created stream.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Create a User

Create a user in Zulip.

Input Parameters:

• Email: User's email address.
• Password: User Password
• FullName: User full name

Output:

• UserId (string): User Id
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Delete a Message

Delete a message in Zulip.

Input Parameters:

• MessageId: ID of the message to delete.

Output:

• Deleted (bool): Whether deletion succeeded.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Delete a Stream

Delete a stream in Zulip.

Input Parameters:

• StreamId: ID of the stream to delete.

Output:

• Deleted (bool): Whether deletion succeeded.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get Many Streams

Get all streams in Zulip.

Output:

• Streams (object-array): List of streams.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get Many Users

Get all users in Zulip.

Output:

• Users (object-array): List of users.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get Subscribed Streams

Get subscribed streams in Zulip.

Output:

• Streams (object-array): List of subscribed streams.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get a Message

Get a message in Zulip.

Input Parameters:

• MessageId: ID of the message to retrieve.

Output:

• Message (object): Message data.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get a User

Get a user in Zulip.

Input Parameters:

• UserId: ID of the user to retrieve.

Output:

• User (object): User data.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Send a Message to Stream

Send a message to a stream in Zulip.

Input Parameters:

• StreamId: Stream id.
• Content: Message content.
• Topic: Optional subject.

Output:

• MessageId (number): ID of the created message.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Send a Private Message

Send a private message in Zulip.

Input Parameters:

• ToEmail: Recipient email.
• Content: Message content.

Output:

• MessageId (number): ID of the created message.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Deactivate a User

Deactivate a user in Zulip.

Input Parameters:

• UserId: ID of the user to deactivate.

Output:

• Deactivated (bool): Whether deactivation succeeded.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Update a Message

Update a message in Zulip.

Input Parameters:

• MessageId: ID of the message to update.
• Content: New message content.

Output:

• Result (string): Update result.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Update a Stream

Update a stream in Zulip.

Input Parameters:

• StreamId: ID of the stream to update.

Options:

• Description: New description for the stream.

Output:

• Stream (object): Updated stream data.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Update a User

Update a user in Zulip.

Input Parameters:

• UserId: ID of the user to update.

Options:

• FullName: New full name for the user.
• Role: New role for the user.

Output:

• Result (string): Update result.
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success), 500 (exception).
• ErrorMessage (string): Error description if any, otherwise an empty string.

5. Example Usage

This section will guide you through creating a simple workflow that sends a notification message to a specific Zulip stream. This is useful for sending alerts from other systems or notifying a team about a completed task.

The workflow will consist of: Start -> Zulip: Send a Message to Stream -> Answer.

Step-by-Step Guide

1. Add the Tool Node
   • In the workflow canvas, click the + button to add a new node.
   • Select the "Tool" tab in the pop-up panel.
   • Find and select "Zulip" from the list of tools.
   • From the list of supported operations for Zulip, click on Send a Message to Stream to add the node to your canvas.
2. Configure the Node
   • Click on the newly added Send a Message to Stream node to open its configuration panel on the right.
   • Credentials: In the "Credentials" field, click the dropdown menu and select your pre-configured Zulip credentials.
   • Parameters: Fill in the required input parameters for the action.
   • StreamId: Enter the numeric ID of the stream you want to send the message to. For example, 123. You can find this ID by using the Get Many Streams operation.
   • Topic: Provide a topic for the message, which acts like a subject line. For example, Workflow Alerts.
   • Content: Type the message you want to send. You can use variables from previous nodes. For example, The data processing workflow has completed successfully.
3. Run and Validate
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
   • Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
   • After a successful run, you can click the log icon (also in the top-right) to view the detailed inputs and outputs of the node, confirming that the message was sent.

After completing these steps, your workflow is fully configured. When triggered, it will automatically post the specified message to your chosen Zulip stream, keeping your team informed.

6. FAQs

Q: Why am I getting an authentication error (401 Unauthorized)?

A: This usually indicates an issue with your credentials. Please check the following:

• Ensure the Bot Email and API Key in your GoInsight credentials exactly match the ones provided by your Zulip organization.
• Verify that the Site URL is correct and accessible.
• Confirm that the bot has the necessary permissions to perform the requested action.

Q: How do I find the StreamId or UserId for an operation?

A: You can use other operations within the Zulip node to retrieve these IDs:

• For Stream IDs: Use the Get Many Streams or Get Subscribed Streams operation. This will return a list of all stream objects, each containing a stream_id and name.
• For User IDs: Use the Get Many Users operation. This will return a list of user objects, each with a user_id and full_name.

Q: Can I send a message to multiple users at once?

A: The Send a Private Message operation is designed for one-to-one communication. To send a message to a group of users, the best practice is to send it to a stream that all target users are subscribed to using the Send a Message to Stream operation.

7. Official Documentation

For more in-depth information about the Zulip API and its capabilities, please refer to the official documentation:

Zulip Official API Documentation