### Install Zulip JavaScript API Source: https://zulip.com/api/installation-instructions Install the Zulip JavaScript API using npm. ```bash npm install zulip-js ``` -------------------------------- ### Typing Start Event Example Source: https://zulip.com/api/get-events This JSON object represents a 'typing' event of type 'start', indicating a user has begun composing a direct message. It includes sender and recipient details. ```json { "id": 0, "message_type": "direct", "op": "start", "recipients": [ { "email": "user8@zulip.testserver", "user_id": 8 }, { "email": "user10@zulip.testserver", "user_id": 10 } ], "sender": { "email": "user10@zulip.testserver", "user_id": 10 }, "type": "typing" } ``` -------------------------------- ### Get All Navigation Views with cURL Source: https://zulip.com/api/get-navigation-views Fetch all navigation views using cURL. This example demonstrates basic HTTP GET authentication using email and API key. ```curl curl -sSX GET -G https://your-org.zulipchat.com/api/v1/navigation_views \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### web_reload_client Event Example Source: https://zulip.com/api/get-events This is an example of the web_reload_client event payload. The 'immediate' flag, when true, instructs the client to fetch a new event queue immediately. ```json { "id": 0, "immediate": true, "type": "web_reload_client" } ``` -------------------------------- ### Install Zulip Python API Source: https://zulip.com/api/installation-instructions Install the Zulip Python API using pip. This command is also included with the Python bindings. ```bash pip install zulip ``` -------------------------------- ### Get Stream Topics in JavaScript Source: https://zulip.com/api/get-stream-topics This JavaScript example demonstrates how to fetch topics from a stream using the zulip-js library. It requires a zuliprc configuration. ```javascript const zulipInit = require("zulip-js"); // Pass the path to your zuliprc file here. const config = { zuliprc: "zuliprc" }; (async () => { const client = await zulipInit(config); // Get all the topics in channel with ID 1 console.log(await client.streams.topics.retrieve({stream_id: 1})); })(); ``` -------------------------------- ### Get Subscriptions via cURL (Basic Authentication) Source: https://zulip.com/api/get-subscriptions Use cURL to make a GET request to the subscriptions endpoint. This example demonstrates basic HTTP authentication using an email address and API key. ```curl curl -sSX GET -G https://your-org.zulipchat.com/api/v1/users/me/subscriptions \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### Example Search Query Source: https://zulip.com/api/construct-narrow This is an example of a search query as it would be entered in the Zulip web app's search box. It demonstrates filtering messages by channel, sender, and keywords. ```text channel:announce -sender:iago@zulip.com cool sunglasses ``` -------------------------------- ### Onboarding Steps Event Example Source: https://zulip.com/api/get-events This event is sent when the set of onboarding steps to be shown to the current user changes. It includes an array of onboarding steps, each with a type and name. ```json { "id": 0, "onboarding_steps": [ { "name": "visibility_policy_banner", "type": "one_time_notice" } ], "type": "onboarding_steps" } ``` -------------------------------- ### Get Attachments with curl Source: https://zulip.com/api/get-attachments Fetch attachment metadata using curl. This example demonstrates basic HTTP GET authentication using email and API key. ```curl curl -sSX GET -G https://your-org.zulipchat.com/api/v1/attachments \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### Create User with Python Source: https://zulip.com/api/create-user Use the Zulip Python client to create a new user. Ensure the user associated with the zuliprc file has organization administrator privileges. ```python #!/usr/bin/env python import zulip # The user for this zuliprc file must be an organization administrator client = zulip.Client(config_file="~/zuliprc-admin") # Create a user. request = { "email": "newbie@zulip.com", "password": "temp", "full_name": "New User", } result = client.create_user(request) print(result) ``` -------------------------------- ### HTML for Linking to Channels Source: https://zulip.com/api/message-formatting Provides HTML examples for linking to channels using Zulip's special Markdown syntax. ```html #announce ``` -------------------------------- ### Get Alert Words with cURL Source: https://zulip.com/api/get-alert-words Use cURL to make a GET request to the Zulip API endpoint for retrieving alert words. This example uses basic authentication with an email address and API key. ```curl curl -sSX GET -G https://your-org.zulipchat.com/api/v1/users/me/alert_words \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### Subscribe to a Channel (Python) Source: https://zulip.com/api/subscribe Use the `zulip.Client` to add subscriptions to one or more channels. If the channel does not exist, it will be created. ```python #!/usr/bin/env python3 import zulip # Pass the path to your zuliprc file here. client = zulip.Client(config_file="~/zuliprc") # Create and subscribe to channel "python-test". result = client.add_subscriptions( streams=[ { "name": "python-test", "description": "Channel for testing Python", }, ], ) # To subscribe other users to a channel, you may pass # the `principals` argument, like so: result = client.add_subscriptions( streams=[{"name": "python-test"}], principals=[user_id], ) print(result) ``` -------------------------------- ### Create a Channel with Python Source: https://zulip.com/api/create-channel Use the Zulip Python client to create a new channel. Ensure you have a zuliprc file configured for authentication. ```python #!/usr/bin/env python3 import zulip # Pass the path to your zuliprc file here. client = zulip.Client(config_file="~/zuliprc") # Create a new channel. request = { "name": "music_group", "description": "Channel for discussing and learning about music.", "subscribers": [12], } result = client.call_endpoint( url="channels/create", method="POST", request=request, ) print(result) ``` -------------------------------- ### Get Realm Emoji (JavaScript) Source: https://zulip.com/api/get-custom-emoji Fetch custom emoji using the zulip-js library. This asynchronous example requires a zuliprc configuration. ```javascript const zulipInit = require("zulip-js"); // Pass the path to your zuliprc file here. const config = { zuliprc: "zuliprc" }; (async () => { const client = await zulipInit(config); console.log(await client.emojis.retrieve()); })(); ``` -------------------------------- ### Example zuliprc File Structure Source: https://zulip.com/api/api-keys A sample `zuliprc` file showing the required key-value pairs for API authentication. This format is used by official Zulip clients. ```ini [api] key= email= site= ... ``` -------------------------------- ### Get Subscription Status Source: https://zulip.com/api/get-subscription-status Checks whether a user is subscribed to a channel. This endpoint is available starting from Zulip 3.0 (feature level 12). ```APIDOC ## GET /api/v1/users/{user_id}/subscriptions/{stream_id} ### Description Check whether a user is subscribed to a channel. ### Method GET ### Endpoint `/api/v1/users/{user_id}/subscriptions/{stream_id}` ### Parameters #### Path Parameters - **user_id** (integer) - Required - The target user's ID. - **stream_id** (integer) - Required - The ID of the channel to access. ### Response #### Success Response (200) - **is_subscribed** (boolean) - Whether the user is subscribed to the channel. - **msg** (string) - An empty string in case of success. - **result** (string) - "success" in case of success. #### Example response(s) ```json { "is_subscribed": false, "msg": "", "result": "success" } ``` ``` -------------------------------- ### Successful JSON Response Example Source: https://zulip.com/api/get-stream-topics A typical successful JSON response from the get stream topics endpoint, listing topics with their max message IDs and names. ```json { "msg": "", "result": "success", "topics": [ { "max_id": 26, "name": "Denmark3" }, { "max_id": 23, "name": "Denmark1" }, { "max_id": 6, "name": "Denmark2" } ] } ``` -------------------------------- ### Get Message Source: https://zulip.com/api/get-message Retrieves a specific message by its ID. The response includes the message content, sender information, and other metadata. It also details how unsupported parameters are handled and provides examples for both successful retrieval and cases where the message is not found or not visible. ```APIDOC ## GET /messages/{message_id} ### Description Retrieves a specific message by its ID. This endpoint returns the full message object, including sender details, content, and timestamps. It also handles cases where unsupported parameters are sent, and provides specific error responses for non-existent or inaccessible messages. ### Method GET ### Endpoint /messages/{message_id} ### Parameters #### Path Parameters - **message_id** (integer) - Required - The ID of the message to retrieve. ### Response #### Success Response (200) - **message** (object) - Contains the details of the retrieved message. - **avatar_url** (string) - The avatar URL of the sender. - **client** (string) - The client that sent the message. - **content** (string) - The HTML-rendered content of the message. - **content_type** (string) - The content type of the message. - **display_recipient** (array) - Information about the recipients of the message. - **flags** (array) - Flags associated with the message (e.g., "read"). - **id** (integer) - The unique ID of the message. - **is_me_message** (boolean) - Whether the message is a "me" message. - **reactions** (array) - A list of reactions to the message. - **recipient_id** (integer) - The ID of the recipient. - **sender_email** (string) - The email address of the sender. - **sender_full_name** (string) - The full name of the sender. - **sender_id** (integer) - The ID of the sender. - **sender_realm_str** (string) - The realm string of the sender. - **subject** (string) - The subject of the message. - **submessages** (array) - Submessages, if any. - **timestamp** (integer) - The Unix timestamp when the message was sent. - **topic_links** (array) - Links related to the topic. - **type** (string) - The type of the recipient (e.g., "private", "stream"). - **msg** (string) - An empty string in case of success. - **raw_content** (string) - The raw, unformatted content of the message. - **result** (string) - "success" indicating the request was successful. - **ignored_parameters_unsupported** (array) - (Zulip 7.0+) An array of parameters that were sent but are not supported by this endpoint. #### Response Example ```json { "message": { "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "client": "ZulipDataImport", "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", "content_type": "text/html", "display_recipient": [ { "email": "hamlet@zulip.com", "full_name": "King Hamlet", "id": 4, "is_mirror_dummy": false }, { "email": "iago@zulip.com", "full_name": "Iago", "id": 5, "is_mirror_dummy": false }, { "email": "prospero@zulip.com", "full_name": "Prospero from The Tempest", "id": 8, "is_mirror_dummy": false } ], "flags": [ "read" ], "id": 16, "is_me_message": false, "reactions": [], "recipient_id": 27, "sender_email": "hamlet@zulip.com", "sender_full_name": "King Hamlet", "sender_id": 4, "sender_realm_str": "zulip", "subject": "", "submessages": [], "timestamp": 1527921326, "topic_links": [], "type": "private" }, "msg": "", "raw_content": "**Don't** forget your towel!", "result": "success" } ``` #### Error Response (400 Bad Request) - **code** (string) - An error code, e.g., "BAD_REQUEST". - **msg** (string) - A message describing the error, e.g., "Invalid message(s)". - **result** (string) - "error" indicating the request failed. #### Response Example ```json { "code": "BAD_REQUEST", "msg": "Invalid message(s)", "result": "error" } ``` ``` -------------------------------- ### Get Server Settings with Python Zulip Client Source: https://zulip.com/api/get-server-settings Use the Python Zulip client library to fetch server settings. Ensure you have a `~/zuliprc` file configured for authentication. ```python #!/usr/bin/env python3 import zulip # Pass the path to your zuliprc file here. client = zulip.Client(config_file="~/zuliprc") # Fetch the settings for this server. result = client.get_server_settings() print(result) ``` -------------------------------- ### Add Subscription Example Source: https://zulip.com/api/get-events This snippet demonstrates the JSON payload structure for adding a subscription to a channel. It includes various settings for the subscription, such as notification preferences and access permissions. ```json { "id": 0, "op": "add", "subscriptions": [ { "audible_notifications": null, "can_add_subscribers_group": 2, "can_remove_subscribers_group": 2, "can_subscribe_group": 2, "color": "#76ce90", "creator_id": null, "description": "", "desktop_notifications": null, "email_notifications": null, "first_message_id": null, "folder_id": 1, "history_public_to_subscribers": true, "in_home_view": true, "invite_only": false, "is_announcement_only": false, "is_archived": false, "is_muted": false, "is_recently_active": true, "is_web_public": false, "message_retention_days": null, "name": "test", "pin_to_top": false, "push_notifications": null, "rendered_description": "", "stream_id": 9, "stream_post_policy": 1, "stream_weekly_traffic": null, "subscribers": [ 10 ], "wildcard_mentions_notify": null } ], "type": "subscription" } ``` -------------------------------- ### Example API Response for Realm Presence Source: https://zulip.com/api/get-presence A typical JSON response from the GET /realm/presence endpoint, showing user presence details including status and timestamp. Note changes in Zulip 7.0 regarding 'aggregated' and 'client' keys. ```json { "msg": "", "presences": { "iago@zulip.com": { "aggregated": { "client": "website", "status": "active", "timestamp": 1656958485 }, "website": { "client": "website", "pushable": false, "status": "active", "timestamp": 1656958485 } } }, "result": "success", "server_timestamp": 1656958539.6287155 } ``` -------------------------------- ### Get Stream by ID Source: https://zulip.com/api/get-stream-by-id Fetches the details of a stream given its unique identifier. The response includes various attributes of the stream such as its name, description, creation date, and subscriber count. It also details how unsupported parameters are handled and provides examples for both successful retrieval and error cases. ```APIDOC ## GET /api/v1/streams/{stream_id} ### Description Retrieves the details of a specific stream using its unique identifier. ### Method GET ### Endpoint /api/v1/streams/{stream_id} ### Parameters #### Path Parameters - **stream_id** (integer) - Required - The ID of the stream to retrieve. ### Response #### Success Response (200) - **msg** (string) - An empty string if the request was successful. - **result** (string) - "success" indicating the request was successful. - **stream** (object) - An object containing the stream's details: - **can_add_subscribers_group** (integer) - **can_remove_subscribers_group** (integer) - **can_subscribe_group** (integer) - **creator_id** (integer or null) - **date_created** (integer) - Unix timestamp of when the stream was created. - **description** (string) - The description of the stream. - **first_message_id** (integer or null) - **folder_id** (integer) - **history_public_to_subscribers** (boolean) - **invite_only** (boolean) - **is_announcement_only** (boolean) - **is_archived** (boolean) - **is_recently_active** (boolean) - **is_web_public** (boolean) - **message_retention_days** (integer or null) - **name** (string) - The name of the stream. - **rendered_description** (string) - The HTML rendered description of the stream. - **stream_id** (integer) - The ID of the stream. - **stream_post_policy** (integer) - **stream_weekly_traffic** (integer or null) - **subscriber_count** (integer) - **ignored_parameters_unsupported** (array) - (Zulip 7.0+) An array of parameters that were sent but are not supported by this endpoint. #### Response Example (Success) ```json { "msg": "", "result": "success", "stream": { "can_add_subscribers_group": 2, "can_remove_subscribers_group": 2, "can_subscribe_group": 2, "creator_id": null, "date_created": 1691057093, "description": "A Scandinavian country", "first_message_id": 1, "folder_id": 1, "history_public_to_subscribers": true, "invite_only": false, "is_announcement_only": false, "is_archived": false, "is_recently_active": true, "is_web_public": false, "message_retention_days": null, "name": "Denmark", "rendered_description": "

A Scandinavian country

", "stream_id": 7, "stream_post_policy": 1, "stream_weekly_traffic": null, "subscriber_count": 12 } } ``` #### Error Response (400 Bad Request) - **code** (string) - "BAD_REQUEST" indicating a bad request. - **msg** (string) - A message describing the error, e.g., "Invalid channel ID". - **result** (string) - "error" indicating the request failed. #### Response Example (Error) ```json { "code": "BAD_REQUEST", "msg": "Invalid channel ID", "result": "error" } ``` ``` -------------------------------- ### Basic Authentication with Authorization Header Source: https://zulip.com/api/http-headers Demonstrates how to authenticate API requests using HTTP Basic authentication with an email address as the username and an API key as the password. ```bash -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### HTML for Linking to Channels and Topics Source: https://zulip.com/api/message-formatting Demonstrates HTML output for linking to specific channels and topics within Zulip. ```html #announce > Zulip updates ``` ```html #announce > Zulip updates ``` -------------------------------- ### Mute User API Response Examples Source: https://zulip.com/api/mute-user Examples of successful and error responses when attempting to mute a user. ```json { "msg": "", "result": "success" } ``` ```json { "code": "BAD_REQUEST", "msg": "Cannot mute self", "result": "error" } ``` ```json { "code": "BAD_REQUEST", "msg": "No such user", "result": "error" } ``` ```json { "code": "BAD_REQUEST", "msg": "User already muted", "result": "error" } ``` -------------------------------- ### Create Constructor Groups Video Call using curl Source: https://zulip.com/api/create-constructor-groups-video-call Use this curl command to create a video call URL. Replace EMAIL_ADDRESS and API_KEY with your Zulip credentials. ```bash curl -sSX POST https://your-org.zulipchat.com/api/v1/calls/constructorgroups/create \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### Example JSON Response for Invalid Bot ID Source: https://zulip.com/api/get-bot-api-key An example JSON response indicating an error when the bot ID is invalid. ```json { "code": "BAD_REQUEST", "msg": "No such bot", "result": "error" } ``` -------------------------------- ### Example Invalid Emoji Code Response Source: https://zulip.com/api/add-reaction An example JSON error response returned when an invalid emoji code is provided. ```json { "code": "BAD_REQUEST", "msg": "Invalid emoji code", "result": "error" } ``` -------------------------------- ### Add Realm User Example Source: https://zulip.com/api/get-events This snippet demonstrates the JSON payload structure for adding a new user to the realm. It includes essential user details like email, full name, and role. ```json { "id": 0, "op": "add", "person": { "avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1", "avatar_version": 1, "date_joined": "2020-07-15T15:04:02.030833+00:00", "delivery_email": null, "email": "foo@zulip.com", "full_name": "full name", "is_active": true, "is_admin": false, "is_bot": false, "is_guest": false, "is_imported_stub": false, "is_owner": false, "profile_data": {}, "role": 400, "timezone": "", "user_id": 38 }, "type": "realm_user" } ``` -------------------------------- ### Get Server Settings Source: https://zulip.com/api/get-server-settings Fetches the server's configuration settings, including authentication methods, Zulip version, and realm details. ```APIDOC ## GET /server-settings ### Description Retrieves configuration information about the Zulip server, including available authentication methods, Zulip version, and realm-specific settings. ### Method GET ### Endpoint /server-settings ### Response #### Success Response (200) - **authentication_methods** (object) - Indicates whether various authentication methods are enabled. - **password** (boolean) - Whether password authentication is enabled. - **dev** (boolean) - Whether development API key authentication is enabled. - **email** (boolean) - Whether email authentication is enabled. - **ldap** (boolean) - Whether LDAP authentication is enabled. - **remoteuser** (boolean) - Whether REMOTE_USER authentication is enabled. - **github** (boolean) - Whether GitHub authentication is enabled. - **azuread** (boolean) - Whether Microsoft Entra ID authentication is enabled. - **gitlab** (boolean) - Whether GitLab authentication is enabled. - **apple** (boolean) - Whether Apple authentication is enabled. - **google** (boolean) - Whether Google authentication is enabled. - **saml** (boolean) - Whether SAML authentication is enabled. - **openid connect** (boolean) - Whether OpenID Connect authentication is enabled. - **discord** (boolean) - Whether Discord authentication is enabled. - **external_authentication_methods** (object[]) - A list of dictionaries describing available external authentication methods. - **name** (string) - A machine-readable name for the authentication method. - **display_name** (string) - The display name for the authentication method. - **display_icon** (string | null) - URL for an icon to be displayed for the authentication method. - **login_url** (string) - URL to initiate authentication with this method. - **signup_url** (string) - URL to initiate account registration with this method. - **zulip_feature_level** (integer) - An integer indicating the feature level of the server. - **zulip_version** (string) - The server's version number. - **zulip_merge_base** (string) - The git merge base between the server's version and official branches. - **push_notifications_enabled** (boolean) - Whether mobile/push notifications are configured. - **is_incompatible** (boolean) - Whether the client is deemed incompatible with the server. - **email_auth_enabled** (boolean) - Whether email-password authentication is allowed. - **require_email_format_usernames** (boolean) - Whether all valid usernames must be email addresses. - **realm_uri** (string) - The organization's canonical URL (deprecated). - **realm_url** (string) - The organization's canonical URL. - **realm_name** (string) - The organization's name. - **realm_icon** (string) - The URL for the organization's logo. - **realm_description** (string) - The organization's description. ``` -------------------------------- ### Error Response Example: Field Not Found Source: https://zulip.com/api/remove-profile-data An example JSON error response when a specified custom profile field ID does not exist. ```json { "code": "BAD_REQUEST", "msg": "Field id 99 not found.", "result": "error" } ``` -------------------------------- ### Error Response Example: Restricted Field Source: https://zulip.com/api/remove-profile-data An example JSON error response when the organization restricts changes to a custom profile field. ```json { "code": "BAD_REQUEST", "msg": "You are not allowed to change this field. Contact an administrator to update it.", "result": "error" } ``` -------------------------------- ### Register Client Device with curl Source: https://zulip.com/api/register-client-device This curl command demonstrates how to register a logged-in device using HTTP Basic authentication. Replace EMAIL_ADDRESS and API_KEY with your actual credentials. ```bash curl -sSX POST https://your-org.zulipchat.com/api/v1/register_client_device \ -u EMAIL_ADDRESS:API_KEY ``` -------------------------------- ### Register Client Device with Python Source: https://zulip.com/api/register-client-device Use this Python snippet to register a logged-in device by calling the `/register_client_device` endpoint. Ensure your zuliprc file is correctly configured. ```python #!/usr/bin/env python3 import zulip # Pass the path to your zuliprc file here. client = zulip.Client(config_file="~/zuliprc") # Register a logged-in device. result = client.call_endpoint(url="/register_client_device", method="POST") print(result) ``` -------------------------------- ### Example Error Response for Non-existent User Source: https://zulip.com/api/get-user-status An example JSON error response returned when the specified user ID does not exist in the organization. ```json { "code": "BAD_REQUEST", "msg": "No such user", "result": "error" } ``` -------------------------------- ### Example Development User List Response Source: https://zulip.com/api/dev-list-users This is a typical successful JSON response from the `dev_list_users` endpoint, showing lists of direct administrators and other users. ```json { "direct_admins": [ { "email": "iago@zulip.com", "realm_url": "http://localhost:9991" } ], "direct_users": [ { "email": "hamlet@zulip.com", "realm_url": "http://localhost:9991" } ], "msg": "", "result": "success" } ``` -------------------------------- ### Example JSON error response for missing stream_id Source: https://zulip.com/api/set-typing-status An example JSON error response when composing a channel message without specifying the stream_id. ```json { "code": "BAD_REQUEST", "msg": "Missing channel ID", "result": "error" } ``` -------------------------------- ### Successful Response Example Source: https://zulip.com/api/create-custom-profile-field This is an example of a successful JSON response when creating a custom profile field. It includes the ID of the newly created field. ```json { "id": 9, "msg": "", "result": "success" } ``` -------------------------------- ### Create a Channel with curl Source: https://zulip.com/api/create-channel Use curl to create a new channel via the Zulip API. This example demonstrates basic authentication using an email address and API key. ```bash curl -sSX POST https://your-org.zulipchat.com/api/v1/channels/create \ -u EMAIL_ADDRESS:API_KEY \ --data-urlencode name=music \ --data-urlencode 'subscribers=[17, 12]' ```