Zulip API

https://zulip.com/api
Admin
Comprehensive REST API documentation for Zulip, an open-source team chat application for productive...
Tokens:266,910
Snippets:2,402
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Typing start event JSON structure

Source: https://zulip.com/api/get-events

Example payload for a direct message typing start event.

```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"
}
```

--------------------------------

### Install Zulip JavaScript API

Source: https://zulip.com/api/installation-instructions

Install the Zulip JavaScript API using npm.

```bash
npm install zulip-js
```

--------------------------------

### 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

```

--------------------------------

### 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

```

--------------------------------

### 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
```

--------------------------------

### Reaction add event example

Source: https://zulip.com/api/get-events

Example JSON payload for a reaction add event.

```json
{
    "emoji_code": "1f389",
    "emoji_name": "tada",
    "id": 0,
    "message_id": 32,
    "op": "add",
    "reaction_type": "unicode_emoji",
    "type": "reaction",
    "user_id": 10
}
```

--------------------------------

### 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

```

--------------------------------

### Drafts add event example

Source: https://zulip.com/api/get-events

Example of an event payload containing details for newly created drafts.

```json
{
    "drafts": [
        {
            "content": "Hello there!",
            "id": 17,
            "timestamp": 15954790200,
            "to": [
                6
            ],
            "topic": "",
            "type": "private"
        }
    ],
    "op": "add",
    "type": "drafts"
}
```

--------------------------------

### realm_bot add event example

Source: https://zulip.com/api/get-events

Example payload for a realm_bot event with the 'add' operation, used for bot administration.

```json
{
    "bot": {
        "default_all_public_streams": false,
        "default_events_register_stream": null,
        "default_sending_stream": null,
        "services": [],
        "user_id": 36
    },
    "id": 1,
    "op": "add",
    "type": "realm_bot"
}
```

--------------------------------

### User Group Add Members Event Example

Source: https://zulip.com/api/get-events

Example payload for an event triggered when users are added to a group.

```json
{
    "group_id": 2,
    "id": 0,
    "op": "add_members",
    "type": "user_group",
    "user_ids": [
        10
    ]
}
```

--------------------------------

### onboarding_steps event example

Source: https://zulip.com/api/get-events

Sent when the user's onboarding or tutorial progress changes.

```json
{
    "id": 0,
    "onboarding_steps": [
        {
            "name": "visibility_policy_banner",
            "type": "one_time_notice"
        }
    ],
    "type": "onboarding_steps"
}
```

--------------------------------

### Typing edit message start event JSON structure

Source: https://zulip.com/api/get-events

Example of a typing_edit_message start event payload sent when a user begins editing a message.

```json
{
    "id": 0,
    "message_id": 7,
    "op": "start",
    "recipient": {
        "type": "direct",
        "user_ids": [
            8,
            10
        ]
    },
    "sender_id": 10,
    "type": "typing_edit_message"
}
```

--------------------------------

### 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)

```

--------------------------------

### 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 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

```

--------------------------------

### 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=<bot API key>
email=<bot email address>
site=<Zulip server's URL>
...

```

--------------------------------

### 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());
})();

```

--------------------------------

### 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)

```

--------------------------------

### 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"
}
```
```

--------------------------------

### 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
```

--------------------------------

### 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": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
        "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"
}
```
```

--------------------------------

### 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
```

--------------------------------

### 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.
```

--------------------------------

### 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
}

```

--------------------------------

### 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

```

--------------------------------

### 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": "<p>A Scandinavian country</p>",
        "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"
}
```
```

--------------------------------

### muted_topics event example

Source: https://zulip.com/api/get-events

Example JSON payload for a muted_topics event.

```json
{
    "id": 0,
    "muted_topics": [
        [
            "Denmark",
            "topic",
            1594825442
        ]
    ],
    "type": "muted_topics"
}
```

--------------------------------

### 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)

```

--------------------------------

### delete_message event example

Source: https://zulip.com/api/get-events

Example JSON payload for a delete_message event.

```json
{
    "id": 0,
    "message_id": 37,
    "message_type": "private",
    "type": "delete_message"
}
```

--------------------------------

### Navigation view add event example

Source: https://zulip.com/api/get-events

Represents the JSON structure for adding a new navigation view.

```json
{
    "navigation_view": {
        "fragment": "narrow/is/alerted",
        "is_pinned": true,
        "name": "Alert Words"
    },
    "op": "add",
    "type": "navigation_view"
}
```

--------------------------------

### Reaction remove event example

Source: https://zulip.com/api/get-events

Example JSON payload for a reaction remove event.

```json
{
    "emoji_code": "1f389",
    "emoji_name": "tada",
    "id": 0,
    "message_id": 52,
    "op": "remove",
    "reaction_type": "unicode_emoji",
    "type": "reaction",
    "user_id": 10
}
```

--------------------------------

### Subscription peer_add event example

Source: https://zulip.com/api/get-events

Represents the JSON structure for a peer_add subscription event.

```json
{
    "id": 0,
    "op": "peer_add",
    "stream_ids": [
        9
    ],
    "type": "subscription",
    "user_ids": [
        12
    ]
}
```

--------------------------------

### Subscribe to channels with Python

Source: https://zulip.com/api/subscribe

Uses the zulip Python client to subscribe to channels, optionally specifying principals to subscribe other users.

```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 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]'

```

--------------------------------

### User Group Update Event Example

Source: https://zulip.com/api/get-events

Example payload for a user group update event.

```json
{
    "data": {
        "description": "Mention this group to get the security team's attention."
    },
    "group_id": 2,
    "id": 0,
    "op": "update",
    "type": "user_group"
}
```

--------------------------------

### update_message_flags remove event example

Source: https://zulip.com/api/get-events

Example JSON payload for an update_message_flags event with the remove operation.

```json
{
    "all": false,
    "flag": "starred",
    "id": 0,
    "message_details": {
        "63": {
            "stream_id": 22,
            "topic": "lunch",
            "type": "stream"
        }
    },
    "messages": [
        63
    ],
    "op": "remove",
    "operation": "remove",
    "type": "update_message_flags"
}
```

--------------------------------

### Create User with JavaScript (zulip-js)

Source: https://zulip.com/api/create-user

Utilize the zulip-js library to programmatically create a new user. The configuration requires a zuliprc file with administrator credentials.

```javascript
const zulipInit = require("zulip-js");

// The user for this zuliprc file must be an organization administrator.
const config = { zuliprc: "zuliprc-admin" };

(async () => {
    const client = await zulipInit(config);

    const params = {
        email: "notnewbie@zulip.com",
        password: "temp",
        full_name: "New User",
    };

    console.log(await client.users.create(params));
})();

```

--------------------------------

### HTML rendering for standard channel and topic links

Source: https://zulip.com/api/message-formatting

HTML structures for linking to channels, topics, and specific messages using Zulip's Markdown syntax.

```html
<!-- Syntax: #**announce** -->
<a class="stream" data-stream-id="9"
  href="/#narrow/channel/9-announce">
 #announce
</a>

<!-- Syntax: #**announce>Zulip updates** -->
<a class="stream-topic" data-stream-id="9"
  href="/#narrow/channel/9-announce/topic/Zulip.20updates/with/214">
 #announce &gt; Zulip updates
</a>

<!-- Syntax: #**announce>Zulip updates**
     Generated only if topic had no messages or the link was rendered
     before Zulip 10.0 (feature level 347) -->
<a class="stream-topic" data-stream-id="9"
  href="/#narrow/channel/9-announce/topic/Zulip.20updates">
 #announce &gt; Zulip updates
</a>

<!-- Syntax: #**announce>Zulip updates@214** -->
<a class="message-link"
  href="/#narrow/channel/9-announce/topic/Zulip.20updates/near/214">
 #announce &gt; Zulip updates @ 💬
</a>
```

--------------------------------

### Register an event queue in JavaScript

Source: https://zulip.com/api/register-queue

Uses the zulip-js library to initialize a client and register for message events.

```javascript
const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Register a queue
    const params = {
        event_types: ["message"],
    };

    console.log(await client.queues.register(params));
})();
```

--------------------------------

### 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"
}

```

--------------------------------

### typing_edit_message op: start

Source: https://zulip.com/api/get-events

Event sent when a user starts typing in a textarea to edit the content of a message.

```APIDOC
## typing_edit_message op: start

### Description
Event sent when a user starts editing a message. Clients requesting this event type will receive it if they would have been notified if the message's content edit were to be saved.

### Fields
- **id** (integer) - The ID of the event.
- **type** (string) - The event's type.
- **sender_id** (integer) - The ID of the user who is typing the edit.
- **message_id** (integer) - The message ID being edited.
- **recipient** (object) - Object containing details about recipients of the notification.

### Example
{
    "id": 0,
    "message_id": 7,
    "op": "start",
    "recipient": {
        "type": "direct",
        "user_ids": [
            8,
            10
        ]
    },
    "sender_id": 10,
    "type": "typing_edit_message"
}
```

--------------------------------

### Get Server Settings with curl

Source: https://zulip.com/api/get-server-settings

Fetch server settings using curl with Basic HTTP authentication. Replace `EMAIL_ADDRESS` and `API_KEY` with your credentials.

```bash
curl -sSX GET -G https://your-org.zulipchat.com/api/v1/server_settings \
    -u EMAIL_ADDRESS:API_KEY

```

--------------------------------

### Realm update event example

Source: https://zulip.com/api/get-events

Example of a realm update event payload used to modify dictionary-based properties.

```json
{
    "data": {
        "message_content_edit_limit_seconds": 600
    },
    "id": 0,
    "op": "update_dict",
    "property": "default",
    "type": "realm"
}
```

--------------------------------

### Example API Response for Channel Folders

Source: https://zulip.com/api/get-channel-folders

This is a typical JSON response when successfully fetching channel folders. It includes a list of folder objects, each with details like ID, name, and creation date.

```json
{
    "channel_folders": [
        {
            "creator_id": 1,
            "date_created": 1691057093,
            "description": "Channels for frontend discussions",
            "id": 1,
            "is_archived": false,
            "name": "Frontend",
            "rendered_description": "<p>Channels for frontend discussions</p>"
        },
        {
            "creator_id": 1,
            "date_created": 1791057093,
            "description": "Channels for **backend** discussions",
            "id": 2,
            "is_archived": false,
            "name": "Backend",
            "rendered_description": "<p>Channels for <strong>backend</strong> discussions</p>"
        }
    ],
    "msg": "",
    "result": "success"
}

```

--------------------------------

### User Group Remove Members Event Example

Source: https://zulip.com/api/get-events

Example payload for an event triggered when users are removed from a group.

```json
{
    "group_id": 2,
    "id": 0,
    "op": "remove_members",
    "type": "user_group",
    "user_ids": [
        10
    ]
}
```

--------------------------------

### Subscription add event example

Source: https://zulip.com/api/get-events

Represents the JSON structure of an event sent when a user is subscribed to a channel.

```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"
}
```

--------------------------------

### Configuring User-Agent in Zulip Python Bindings

Source: https://zulip.com/api/http-headers

Shows how to set a custom User-Agent string when initializing the Zulip Python bindings for an integration.

```python
client = zulip.Client(
    config_file=opts.config, client=f"ZulipNagios/{VERSION}"
)
```
Tokens:
Raw