mirror of https://github.com/zulip/zulip.git
24800 lines
1.1 MiB
24800 lines
1.1 MiB
# This file contains the API definitions for the Zulip REST API.
|
|
#
|
|
# For details on the OpenAPI specification, see https://swagger.io/specification
|
|
#
|
|
# Our own documentation lives at
|
|
#
|
|
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
|
|
#
|
|
|
|
openapi: 3.0.1
|
|
info:
|
|
version: 1.0.0
|
|
title: Zulip REST API
|
|
description: |
|
|
Powerful open source group chat
|
|
contact:
|
|
url: https://zulip.com
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
servers:
|
|
# Zulip Cloud
|
|
- url: "https://{subdomain}.zulipchat.com/api/v1"
|
|
variables:
|
|
subdomain:
|
|
default: example
|
|
# Self-hosted
|
|
- url: "{server}/api/v1"
|
|
variables:
|
|
server:
|
|
default: https://
|
|
# chat.zulip.org
|
|
- url: "https://chat.zulip.org/api/v1"
|
|
# Development server
|
|
- url: "http://localhost:9991/api/v1"
|
|
# Test suite
|
|
- url: "http://{subdomain}.testserver/json"
|
|
security:
|
|
- basicAuth: []
|
|
#######################
|
|
# Endpoint definitions
|
|
#######################
|
|
paths:
|
|
/fetch_api_key:
|
|
post:
|
|
operationId: fetch-api-key
|
|
summary: Fetch an API key (production)
|
|
tags: ["authentication"]
|
|
description: |
|
|
This API endpoint is used by clients such as the Zulip mobile and
|
|
terminal apps to implement password-based authentication. Given the
|
|
user's Zulip login credentials, it returns a Zulip API key that the client
|
|
can use to make requests as the user.
|
|
|
|
This endpoint is only useful for Zulip servers/organizations with
|
|
EmailAuthBackend or LDAPAuthBackend enabled.
|
|
|
|
The Zulip mobile apps also support SSO/social authentication (GitHub
|
|
auth, Google auth, SAML, etc.) that does not use this endpoint. Instead,
|
|
the mobile apps reuse the web login flow passing the `mobile_flow_otp` in
|
|
a webview, and the credentials are returned to the app (encrypted) via a redirect
|
|
to a `zulip://` URL.
|
|
|
|
!!! warn ""
|
|
|
|
**Note:** If you signed up using passwordless authentication and
|
|
never had a password, you can [reset your password](/help/change-your-password).
|
|
|
|
See the [API keys](/api/api-keys) documentation for more details
|
|
on how to download an API key manually.
|
|
|
|
In a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
|
|
see also [the unauthenticated variant](/api/dev-fetch-api-key).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
description: |
|
|
The username to be used for authentication (typically, the email
|
|
address, but depending on configuration, it could be an LDAP username).
|
|
|
|
See the `require_email_format_usernames` parameter documented in
|
|
[GET /server_settings](/api/get-server-settings) for details.
|
|
type: string
|
|
example: iago@zulip.com
|
|
password:
|
|
type: string
|
|
example: abcd1234
|
|
description: |
|
|
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
required:
|
|
- username
|
|
- password
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: |
|
|
Valid credentials the client can use to access the Zulip API:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ApiKeyResponse"
|
|
/dev_fetch_api_key:
|
|
post:
|
|
operationId: dev-fetch-api-key
|
|
summary: Fetch an API key (development only)
|
|
tags: ["authentication"]
|
|
description: |
|
|
For easy testing of mobile apps and other clients and against Zulip
|
|
development servers, we support fetching a Zulip API key for any user
|
|
on the development server without authentication (so that they can
|
|
implement analogues of the one-click login process available for Zulip
|
|
development servers on the web).
|
|
|
|
!!! warn ""
|
|
|
|
**Note:** This endpoint is only available on Zulip development
|
|
servers; for obvious security reasons it will always return an error
|
|
in a Zulip production server.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
description: |
|
|
The email address for the user that owns the API key.
|
|
type: string
|
|
example: iago@zulip.com
|
|
required:
|
|
- username
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ApiKeyResponse"
|
|
/events:
|
|
get:
|
|
operationId: get-events
|
|
summary: Get events from an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
This endpoint allows you to receive new events from
|
|
[a registered event queue](/api/register-queue).
|
|
|
|
Long-lived clients should use the
|
|
`event_queue_longpoll_timeout_seconds` property returned by
|
|
`POST /register` as the client-side HTTP request timeout for
|
|
calls to this endpoint. It is guaranteed to be higher than
|
|
heartbeat frequency and should be respected by clients to
|
|
avoid breaking when heartbeat frequency increases.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- queue_id
|
|
- last_event_id
|
|
x-parameter-description: |
|
|
!!! warn ""
|
|
|
|
**Note**: The parameters documented above are optional in the sense that
|
|
even if you haven't registered a queue by explicitly requesting the
|
|
`POST /register` endpoint, you could pass the parameters for
|
|
[the `POST /register` endpoint](/api/register-queue) to this
|
|
endpoint and a queue would be registered in the absence of a `queue_id`.
|
|
x-python-examples-extra-imports: ["sys"]
|
|
parameters:
|
|
- $ref: "#/components/parameters/QueueId"
|
|
- name: last_event_id
|
|
in: query
|
|
description: |
|
|
The highest event ID in this queue that you've received and
|
|
wish to acknowledge. See the [code for
|
|
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)
|
|
in the [zulip Python
|
|
module](https://github.com/zulip/python-zulip-api) for an
|
|
example implementation of correctly processing each event
|
|
exactly once.
|
|
schema:
|
|
type: integer
|
|
example: -1
|
|
- name: dont_block
|
|
in: query
|
|
description: |
|
|
Set to `true` if the client is requesting a nonblocking reply. If not
|
|
specified, the request will block until either a new event is available
|
|
or a few minutes have passed, in which case the server will send the
|
|
client a heartbeat event.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
events:
|
|
type: array
|
|
description: |
|
|
An array of `event` objects (possibly zero-length if `dont_block` is
|
|
set) with IDs newer than `last_event_id`. Event IDs are
|
|
guaranteed to be increasing, but they are not guaranteed to be
|
|
consecutive.
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of configured
|
|
[alert words](/help/dm-mention-alert-notifications#alert-words) have changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- alert_words
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "alert_words",
|
|
"alert_words": ["alert_word"],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to clients that have requested the
|
|
`update_display_settings` event type and did not include
|
|
`user_settings_object` in their `client_capabilities` when
|
|
registering the event queue.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
deprecated: true
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_display_settings
|
|
user:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
setting_name:
|
|
type: string
|
|
description: |
|
|
Name of the changed display setting.
|
|
setting:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
language_name:
|
|
description: |
|
|
Present only if the setting to be changed is
|
|
`default_language`. Contains the name of the
|
|
new default language in English.
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "update_display_settings",
|
|
"user": "iago@zulip.com",
|
|
"setting_name": "high_contrast_mode",
|
|
"setting": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's [notification
|
|
settings](/api/update-settings) have changed with an additional
|
|
rule that it is only sent to clients that did not include
|
|
`user_settings_object` in their `client_capabilities` when
|
|
registering the event queue.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
deprecated: true
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_global_notifications
|
|
user:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
notification_name:
|
|
type: string
|
|
description: |
|
|
Name of the changed notification setting.
|
|
setting:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "update_global_notifications",
|
|
"user": "iago@zulip.com",
|
|
"notification_name": "enable_sounds",
|
|
"setting": true,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's settings
|
|
have changed.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 89), replacing the
|
|
previous `update_display_settings` and `update_global_notifications`
|
|
event types, which are still present for backwards compatibility reasons.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_settings
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
Name of the changed setting.
|
|
value:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
language_name:
|
|
description: |
|
|
Present only if the setting to be changed is
|
|
`default_language`. Contains the name of the
|
|
new default language in English.
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "user_settings",
|
|
"op": "update",
|
|
"property": "high_contrast_mode",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent generally to all users who can access the modified
|
|
user for changes in the set of users or those users metadata.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 228), this event
|
|
was sent to all users in the organization.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
person:
|
|
description: |
|
|
Object containing the changed details of the user.
|
|
It has multiple forms depending on the value changed.
|
|
oneOf:
|
|
- type: object
|
|
description: |
|
|
When a user changes their full name.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of modified user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The new full name for the user.
|
|
additionalProperties: false
|
|
- type: object
|
|
description: |
|
|
When a user changes their avatar.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who is affected by this change.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
The URL of the new avatar for the user.
|
|
avatar_source:
|
|
type: string
|
|
description: |
|
|
The new avatar data source type for the user.
|
|
|
|
Value values are `G` (gravatar) and `U` (uploaded by user).
|
|
avatar_url_medium:
|
|
type: string
|
|
description: |
|
|
The new medium-size avatar URL for user.
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
The version number for the user's avatar. This is useful
|
|
for cache-busting.
|
|
additionalProperties: false
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When a user changes their time zone setting.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of modified user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
|
|
**Deprecated**: This field will be removed in a future
|
|
release as it is redundant with the `user_id`.
|
|
deprecated: true
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The new time zone of the user.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the owner of a bot changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user/bot whose owner has changed.
|
|
bot_owner_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the new bot owner.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the [role](/help/roles-and-permissions) of a user changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
role:
|
|
type: integer
|
|
description: |
|
|
The new [role](/api/roles-and-permissions) of the user.
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When billing role of a user changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is now a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the value of a user's delivery email as visible to you changes,
|
|
either due to the email address changing or your access to the user's
|
|
email changing via an update to their `email_address_visibility`
|
|
setting.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this event was
|
|
sent only to the affected user, and this event would only be triggered
|
|
by changing the affected user's delivery email.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
delivery_email:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The new delivery email of the user.
|
|
|
|
This value can be `null` if the affected user
|
|
changed their `email_address_visibility` setting
|
|
such that you cannot access their real email.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163),
|
|
`null` was not a possible value for this event as
|
|
it was only sent to the affected user when their
|
|
email address was changed.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the user updates one of their custom profile
|
|
fields.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
custom_profile_field:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about the custom
|
|
profile data change.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field which user updated.
|
|
value:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
User's personal value for this custom profile field,
|
|
or `null` if unset.
|
|
rendered_value:
|
|
type: string
|
|
description: |
|
|
The `value` rendered in HTML. Will only be present for
|
|
custom profile field types that support Markdown rendering.
|
|
|
|
This user-generated HTML content should be rendered
|
|
using the same CSS and client-side security protections
|
|
as are used for message content.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the Zulip API email address of a user changes,
|
|
either due to the user's email address changing, or
|
|
due to changes in the user's
|
|
[email address visibility][help-email-visibility].
|
|
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
new_email:
|
|
type: string
|
|
description: |
|
|
The new value of `email` for the user. The client
|
|
should update any data structures associated
|
|
with this user to use this new value as the
|
|
user's Zulip API email address.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When a user is deactivated or reactivated. Only
|
|
users who can access the modified user under the
|
|
organization's `can_access_all_users_group` policy
|
|
will receive this event.
|
|
|
|
Clients receiving a deactivation event should
|
|
remove the user from all user groups in their data
|
|
structures, because deactivated users cannot be
|
|
members of groups.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level
|
|
303), reactivation events were sent to users who
|
|
could not access the reactivated user due to a
|
|
`can_access_all_users_group` policy. Also,
|
|
previously, Clients were not required to update
|
|
group membership records during user deactivation.
|
|
|
|
New in Zulip 8.0 (feature level 222). Previously the server
|
|
sent a `realm_user` event with `op` field set to `remove`
|
|
when deactivating a user and a `realm_user` event with `op`
|
|
field set to `add` when reactivating a user.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean describing whether the user account has been deactivated.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "update",
|
|
"person":
|
|
{
|
|
"avatar_source": "G",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
|
|
"avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
|
|
"avatar_version": 3,
|
|
"user_id": 10,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's channel subscriptions
|
|
have changed (either the set of subscriptions or their properties).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary contains
|
|
information about one of the subscribed channels.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 8.0 (feature level 226).
|
|
|
|
Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "add",
|
|
"subscriptions":
|
|
[
|
|
{
|
|
"name": "test",
|
|
"stream_id": 9,
|
|
"is_archived": false,
|
|
"creator_id": null,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"color": "#76ce90",
|
|
"is_muted": false,
|
|
"pin_to_top": false,
|
|
"audible_notifications": null,
|
|
"desktop_notifications": null,
|
|
"email_notifications": null,
|
|
"push_notifications": null,
|
|
"wildcard_mentions_notify": null,
|
|
"in_home_view": true,
|
|
"stream_weekly_traffic": null,
|
|
"can_remove_subscribers_group": 2,
|
|
"subscribers": [10],
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user has been unsubscribed
|
|
from one or more channels.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries, where each dictionary contains
|
|
information about one of the newly unsubscribed channels.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing details about the unsubscribed channel.
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the channel.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "remove",
|
|
"subscriptions":
|
|
[{"name": "test", "stream_id": 9}],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when a property of the user's
|
|
subscription to a channel has been updated. This event is used
|
|
only for personal properties like `is_muted` or `pin_to_top`.
|
|
See the [`stream op: update` event](/api/get-events#stream-update)
|
|
for updates to global properties of a channel.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel whose subscription details have changed.
|
|
property:
|
|
type: string
|
|
description: |
|
|
The property of the subscription which has changed. For details on the
|
|
various subscription properties that a user can change, see
|
|
[POST /users/me/subscriptions/properties](/api/update-subscription-settings).
|
|
|
|
Clients should generally handle an unknown property received here without
|
|
crashing, since that will naturally happen when connecting to a Zulip
|
|
server running a new version that adds a new subscription property.
|
|
|
|
**Changes**: As of Zulip 6.0 (feature level 139), updates to the `is_muted`
|
|
property or the deprecated `in_home_view` property will send two `subscription`
|
|
update events, one for each property, to support clients fully migrating to
|
|
use the `is_muted` property. Prior to this feature level, updates to either
|
|
property only sent one event with the deprecated `in_home_view` property.
|
|
value:
|
|
description: |
|
|
The new value of the changed property.
|
|
oneOf:
|
|
- type: integer
|
|
- type: boolean
|
|
- type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"op": "update",
|
|
"type": "subscription",
|
|
"property": "pin_to_top",
|
|
"value": true,
|
|
"stream_id": 11,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when another user subscribes to a channel, or their
|
|
subscription is newly visible to the current user.
|
|
|
|
When a user subscribes to a channel, the current user will receive this
|
|
event only if they [have permission to see the channel's subscriber
|
|
list](/help/channel-permissions). When the current user gains permission
|
|
to see a given channel's subscriber list, they will receive this event
|
|
for the existing subscriptions to the channel.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
|
|
incorrectly not sent to guest users when subscribers to web-public
|
|
channels and subscribed public channels changed.
|
|
|
|
Prior to Zulip 8.0 (feature level 205), this event was not sent when
|
|
a user gained access to a channel due to their [role
|
|
changing](/help/roles-and-permissions).
|
|
|
|
Prior to Zulip 6.0 (feature level 134), this event was not sent when a
|
|
private channel was made public.
|
|
|
|
In Zulip 4.0 (feature level 35), the singular `user_id` and `stream_id`
|
|
integers included in this event were replaced with plural `user_ids` and
|
|
`stream_ids` integer arrays.
|
|
|
|
In Zulip 3.0 (feature level 19), the `stream_id` field was added to
|
|
identify the channel the user subscribed to, replacing the `name` field.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- peer_add
|
|
stream_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of channels that have new or updated subscriber data.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 35), replacing
|
|
the `stream_id` integer.
|
|
items:
|
|
type: integer
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the users who are newly visible as subscribed to
|
|
the specified channels.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 35), replacing
|
|
the `user_id` integer.
|
|
items:
|
|
type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "peer_add",
|
|
"stream_ids": [9],
|
|
"user_ids": [12],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to other users when users have been unsubscribed
|
|
from channels. Sent to all users if the channel is public or to only
|
|
the existing subscribers if the channel is private.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
|
|
incorrectly not sent to guest users when subscribers to web-public
|
|
channels and subscribed public channels changed.
|
|
|
|
In Zulip 4.0 (feature level 35), the singular `user_id` and
|
|
`stream_id` integers included in this event were replaced
|
|
with plural `user_ids` and `stream_ids` integer arrays.
|
|
|
|
In Zulip 3.0 (feature level 19), the `stream_id` field was
|
|
added to identify the channel the user unsubscribed from,
|
|
replacing the `name` field.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- peer_remove
|
|
stream_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the channels from which the users have been
|
|
unsubscribed from.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 35), replacing
|
|
the `stream_id` integer.
|
|
items:
|
|
type: integer
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the users who have been unsubscribed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 35), replacing
|
|
the `user_id` integer.
|
|
items:
|
|
type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "peer_remove",
|
|
"stream_ids": [9],
|
|
"user_ids": [12],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event type for messages.
|
|
|
|
**Changes**: In Zulip 3.1 (feature level 26), the
|
|
`sender_short_name` field was removed from message
|
|
objects.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- message
|
|
message:
|
|
$ref: "#/components/schemas/MessagesEvent"
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
Clients should inspect the flags field rather than assuming that
|
|
new messages are unread; [muted users](/api/mute-user), messages
|
|
sent by the current user, and more subtle scenarios can result
|
|
in a new message that the server has already marked as read for
|
|
the user.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
|
|
flag was deprecated in favor of the `stream_wildcard_mentioned` and
|
|
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
|
|
for backwards compatibility with older clients and equals
|
|
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
|
|
supporting older server versions should treat this field as a previous
|
|
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
|
|
were not available prior to this feature level.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "message",
|
|
"message":
|
|
{
|
|
"id": 31,
|
|
"sender_id": 10,
|
|
"content": '<p>First message ...<a href="user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt">zulip.txt</a></p>',
|
|
"recipient_id": 23,
|
|
"timestamp": 1594825416,
|
|
"client": "test suite",
|
|
"subject": "test",
|
|
"topic_links": [],
|
|
"is_me_message": false,
|
|
"reactions": [],
|
|
"submessages": [],
|
|
"sender_full_name": "King Hamlet",
|
|
"sender_email": "user10@zulip.testserver",
|
|
"sender_realm_str": "zulip",
|
|
"display_recipient": "Denmark",
|
|
"type": "stream",
|
|
"stream_id": 1,
|
|
"avatar_url": null,
|
|
"content_type": "text/html",
|
|
},
|
|
"flags": [],
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when the user completes the
|
|
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
|
|
to know whether initiating Zoom OAuth is required before creating a Zoom call.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- has_zoom_token
|
|
value:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user has zoom
|
|
token or not.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "has_zoom_token",
|
|
"value": true,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
A simple event sent when the set of invitations changes.
|
|
This event is sent to organization administrators and the creator of
|
|
the changed invitation; this tells clients they need to refetch
|
|
data from `GET /invites` if they are displaying UI containing active
|
|
invitations.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 209), this event was
|
|
only sent to organization administrators.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- invites_changed
|
|
additionalProperties: false
|
|
example: {"type": "invites_changed", "id": 0}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users in a Zulip organization when a new
|
|
user joins or when a guest user gains access to a user.
|
|
Processing this event is important to being able to display
|
|
basic details on other users given only their ID.
|
|
|
|
If the current user is a guest whose access to a newly created user
|
|
is limited by a `can_access_all_users_group` policy, and the event
|
|
queue was registered with the `user_list_incomplete` client
|
|
capability, then the event queue will not receive an event for such
|
|
a new user. If a newly created user is inaccessible to the current
|
|
user via such a policy, but the client lacks `user_list_incomplete`
|
|
client capability, then this event will be delivered to the queue,
|
|
with an "Unknown user" object with the usual format but placeholder
|
|
data whose only variable content is the user ID.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 232), the
|
|
`user_list_incomplete` client capability did not exist, and so all
|
|
clients whose access to a new user was prevented by
|
|
`can_access_all_users_group` policy would receive a fake "Unknown
|
|
user" event for such a user.
|
|
|
|
Starting with Zulip 8.0 (feature level 228),
|
|
this event is also sent when a guest user gains access to
|
|
a user.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
person:
|
|
$ref: "#/components/schemas/User"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "add",
|
|
"person":
|
|
{
|
|
"email": "foo@zulip.com",
|
|
"delivery_email": null,
|
|
"user_id": 38,
|
|
"avatar_version": 1,
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_guest": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"is_bot": false,
|
|
"full_name": "full name",
|
|
"timezone": "",
|
|
"is_active": true,
|
|
"date_joined": "2020-07-15T15:04:02.030833+00:00",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
|
|
"profile_data": {},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to guest users when they lose access to a user.
|
|
|
|
**Changes**: As of Zulip 8.0 (feature level 228), this event is no
|
|
longer deprecated.
|
|
|
|
In Zulip 8.0 (feature level 222), this event was deprecated and no
|
|
longer sent to clients. Prior to this feature level, it was sent to all
|
|
users in a Zulip organization when a user was deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
person:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the deactivated user.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deactivated user.
|
|
full_name:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The full name of the user.
|
|
|
|
**Deprecated**: We expect to remove this field in the future.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "remove",
|
|
"person":
|
|
{"user_id": 35, "full_name": "Foo Bot"},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users in an organization when a user comes
|
|
back online after being offline for a while. While most presence
|
|
updates are done via polling the [main presence
|
|
endpoint](/api/get-presence), this event is important to avoid
|
|
confusing users when someone comes online and immediately sends
|
|
a message (one wouldn't want them to still appear offline at
|
|
that point!).
|
|
|
|
If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level
|
|
setting is set to `true`, then the event is only sent to users
|
|
who can access the user who came back online.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 228), this event
|
|
was sent to all users in the organization.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- presence
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the modified user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
|
|
**Deprecated**: This field will be removed in a future
|
|
release as it is redundant with the `user_id`.
|
|
deprecated: true
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
The timestamp of when the Zulip server received the user's
|
|
presence as a UNIX timestamp.
|
|
presence:
|
|
type: object
|
|
description: |
|
|
Object containing the details of the user's most recent presence.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{client_name}`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `"website"` as the server no longer stores which
|
|
client submitted presence updates.
|
|
|
|
Previously, the object key was the client's platform name, for
|
|
example `website` or `ZulipDesktop`.
|
|
additionalProperties: false
|
|
properties:
|
|
client:
|
|
type: string
|
|
description: |
|
|
The client's platform name.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `"website"` as the server no longer stores which
|
|
client submitted presence updates.
|
|
status:
|
|
type: string
|
|
enum:
|
|
- idle
|
|
- active
|
|
description: |
|
|
The status of the user on this client. Will be either `idle`
|
|
or `active`.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of when this client sent the user's presence
|
|
to the server with the precision of a second.
|
|
pushable:
|
|
type: boolean
|
|
description: |
|
|
Whether the client is capable of showing mobile/push notifications
|
|
to the user.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `false` as the server no longer stores which
|
|
client submitted presence updates.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "presence",
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"server_timestamp": 1594825445.320078373,
|
|
"presence":
|
|
{
|
|
"website":
|
|
{
|
|
"client": "website",
|
|
"status": "idle",
|
|
"timestamp": 1594825445,
|
|
"pushable": false,
|
|
},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a new channel is created to users who can see
|
|
the new channel exists (for private channels, only subscribers and
|
|
organization administrators will receive this event).
|
|
|
|
This event is also sent when a user gains access to a channel they
|
|
previously [could not access](/help/channel-permissions), such as
|
|
when their [role](/help/roles-and-permissions) changes, a
|
|
private channel is made public, or a guest user is subscribed
|
|
to a public (or private) channel.
|
|
|
|
Note that organization administrators who are not subscribed will
|
|
not be able to see content on the channel; just that it exists.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
|
|
incorrectly not sent to guest users a web-public channel was created.
|
|
|
|
Prior to Zulip 8.0 (feature level 205), this event was not sent
|
|
when a user gained access to a channel due to their role changing.
|
|
|
|
Prior to Zulip 8.0 (feature level 192), this event was not sent
|
|
when guest users gained access to a public channel by being
|
|
subscribed.
|
|
|
|
Prior to Zulip 6.0 (feature level 134), this event was not sent
|
|
when a private channel was made public.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- create
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array of objects, each containing
|
|
details about the newly added channel(s).
|
|
items:
|
|
$ref: "#/components/schemas/BasicChannel"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"op": "create",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "private",
|
|
"stream_id": 12,
|
|
"is_archived": false,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"date_created": 1691057093,
|
|
"creator_id": 11,
|
|
"invite_only": true,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": false,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
"stream_weekly_traffic": null,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users who can see a channel when it is deactivated.
|
|
|
|
This event is also sent when a user loses access to a channel they
|
|
previously [could access](/help/channel-permissions) because they
|
|
are unsubscribed from a private channel or their [role](/help/roles-and-permissions)
|
|
has changed.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 205), this event was
|
|
not sent when a user lost access to a channel due to their role
|
|
changing.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- delete
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array of objects, each containing
|
|
details about a channel that was deleted.
|
|
items:
|
|
$ref: "#/components/schemas/BasicChannel"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"op": "delete",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "private",
|
|
"stream_id": 12,
|
|
"is_archived": true,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"date_created": 1691057093,
|
|
"creator_id": 11,
|
|
"invite_only": true,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": false,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
"stream_weekly_traffic": null,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users who can see that a channel exists
|
|
when a property of that channel changes. See
|
|
[GET /streams](/api/get-streams#response) response
|
|
for details on the various properties of a channel.
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 256), this event
|
|
was never sent when the `first_message_id` property of a channel
|
|
was updated because the oldest message that had been sent to it
|
|
changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel whose details have changed.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the channel whose details have changed.
|
|
property:
|
|
type: string
|
|
description: |
|
|
The property of the channel which has changed. See
|
|
[GET /streams](/api/get-streams#response) response for details
|
|
on the various properties of a channel.
|
|
|
|
Clients should handle an "unknown" property received here without
|
|
crashing, since that can happen when connecting to a server running a
|
|
newer version of Zulip with new features.
|
|
value:
|
|
description: |
|
|
The new value of the changed property.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 320), this
|
|
field can be an object for `can_remove_subscribers_group` property,
|
|
which is a [group-setting value][setting-values], when the setting
|
|
is set to a combination of users and groups.
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
oneOf:
|
|
- type: object
|
|
additionalProperties: false
|
|
properties:
|
|
direct_members:
|
|
description: |
|
|
The list of IDs of individual users in the collection of users with this permission.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
direct_subgroups:
|
|
description: |
|
|
The list of IDs of the groups in the collection of users with this permission.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
If an object, it will be a [group-setting value][setting-values] with these fields:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
- type: integer
|
|
- type: boolean
|
|
- type: string
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
Note: Only present if the changed property was `description`.
|
|
|
|
The short description of the channel rendered as HTML, intended to
|
|
be used when displaying the channel description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Note: Only present if the changed property was `invite_only`.
|
|
|
|
Whether the history of the channel is public to its subscribers.
|
|
|
|
Currently always true for public channels (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Note: Only present if the changed property was `invite_only`.
|
|
|
|
Whether the channel's history is now readable by web-public spectators.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 71).
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"op": "update",
|
|
"type": "stream",
|
|
"property": "invite_only",
|
|
"value": true,
|
|
"history_public_to_subscribers": true,
|
|
"is_web_public": false,
|
|
"stream_id": 11,
|
|
"name": "test",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a reaction is added to a message.
|
|
Sent to all users who were recipients of the message.
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiReactionEvent"
|
|
- additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- reaction
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message to which a reaction was
|
|
added.
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
example:
|
|
{
|
|
"type": "reaction",
|
|
"op": "add",
|
|
"user_id": 10,
|
|
"user":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
"message_id": 32,
|
|
"emoji_name": "tada",
|
|
"emoji_code": "1f389",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a reaction is removed from a message.
|
|
Sent to all users who were recipients of the message.
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiReactionEvent"
|
|
- additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- reaction
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message from which the reaction was
|
|
removed.
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
example:
|
|
{
|
|
"type": "reaction",
|
|
"op": "remove",
|
|
"user_id": 10,
|
|
"user":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
"message_id": 52,
|
|
"emoji_name": "tada",
|
|
"emoji_code": "1f389",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when the user uploads a new file
|
|
in a Zulip message. Useful to implement live update in UI showing all files
|
|
the current user has uploaded.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
attachment:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "add",
|
|
"attachment":
|
|
{
|
|
"id": 1,
|
|
"name": "zulip.txt",
|
|
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
|
|
"size": 6,
|
|
"create_time": 1594825414000,
|
|
"messages": [],
|
|
},
|
|
"upload_space_used": 6,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when details of a file that user
|
|
uploaded are changed. Most updates will be changes in the list of
|
|
messages that reference the uploaded file.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
attachment:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "update",
|
|
"attachment":
|
|
{
|
|
"id": 1,
|
|
"name": "zulip.txt",
|
|
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
|
|
"size": 6,
|
|
"create_time": 1594825414000,
|
|
"messages": [],
|
|
},
|
|
"upload_space_used": 6,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when the user deletes a file
|
|
they had uploaded. Useful primarily for UI showing all the files
|
|
the current user has uploaded.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
attachment:
|
|
type: object
|
|
description: |
|
|
Dictionary containing the ID of the deleted attachment.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deleted attachment.
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "remove",
|
|
"attachment": {"id": 1},
|
|
"upload_space_used": 0,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a submessage is added to a message.
|
|
|
|
Submessages are an **experimental** API used for widgets such as the
|
|
`/poll` widget in Zulip.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- submessage
|
|
msg_type:
|
|
type: string
|
|
description: |
|
|
The type of the message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The new content of the submessage.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message to which the submessage has been added.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
submessage_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the submessage.
|
|
example:
|
|
{
|
|
"type": "submessage",
|
|
"msg_type": "widget",
|
|
"message_id": 970461,
|
|
"submessage_id": 4737,
|
|
"sender_id": 58,
|
|
"content": '{"type":"vote","key":"58,1","vote":1}',
|
|
"id": 28,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users who can access the modified
|
|
user when the status of a user changes.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 228),
|
|
this event was sent to all users in the organization.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_status
|
|
away:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether the user has marked themself "away" with this status.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
The text content of the status message.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
or writing a message.
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
The [emoji name](/api/update-status#parameter-emoji_name) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
The [emoji code](/api/update-status#parameter-emoji_code) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
reaction_type:
|
|
type: string
|
|
enum:
|
|
- unicode_emoji
|
|
- realm_emoji
|
|
- zulip_extra_emoji
|
|
description: |
|
|
The [emoji type](/api/update-status#parameter-reaction_type) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user whose status changed.
|
|
example:
|
|
{
|
|
"type": "user_status",
|
|
"user_id": 10,
|
|
"away": true,
|
|
"status_text": "out to lunch",
|
|
"emoji_name": "car",
|
|
"emoji_code": "1f697",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when new custom
|
|
profile field types are configured for that Zulip organization.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- custom_profile_fields
|
|
fields:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details of a single new custom profile field for the Zulip
|
|
organization.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
example:
|
|
{
|
|
"type": "custom_profile_fields",
|
|
"fields":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Phone number",
|
|
"type": 1,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 1,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Biography",
|
|
"type": 2,
|
|
"hint": "What are you known for?",
|
|
"field_data": "",
|
|
"order": 2,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Favorite food",
|
|
"type": 1,
|
|
"hint": "Or drink, if you'd prefer",
|
|
"field_data": "",
|
|
"order": 3,
|
|
"required": false,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 4,
|
|
"name": "Favorite editor",
|
|
"type": 3,
|
|
"hint": "",
|
|
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
|
|
"order": 4,
|
|
"display_in_profile_summary": true,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 5,
|
|
"name": "Birthday",
|
|
"type": 4,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 5,
|
|
"required": false,
|
|
"editable_by_user": false,
|
|
},
|
|
{
|
|
"id": 6,
|
|
"name": "Favorite website",
|
|
"type": 5,
|
|
"hint": "Or your personal blog's URL",
|
|
"field_data": "",
|
|
"order": 6,
|
|
"display_in_profile_summary": true,
|
|
"required": false,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 7,
|
|
"name": "Mentor",
|
|
"type": 6,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 7,
|
|
"required": true,
|
|
"editable_by_user": false,
|
|
},
|
|
{
|
|
"id": 8,
|
|
"name": "GitHub",
|
|
"type": 7,
|
|
"hint": "Enter your GitHub username",
|
|
"field_data": '{"subtype":"github"}',
|
|
"order": 8,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when an organization
|
|
administrator changes the organization's configured default channel groups.
|
|
|
|
Default channel groups are an **experimental** feature that is not yet
|
|
stabilized.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- default_stream_groups
|
|
default_stream_groups:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary
|
|
contains details about a single default channel group.
|
|
items:
|
|
$ref: "#/components/schemas/DefaultChannelGroup"
|
|
example:
|
|
{
|
|
"type": "default_stream_groups",
|
|
"default_stream_groups":
|
|
[
|
|
{
|
|
"name": "group1",
|
|
"id": 2,
|
|
"description": "New description",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "Scotland",
|
|
"stream_id": 3,
|
|
"is_archived": false,
|
|
"description": "Located in the United Kingdom",
|
|
"rendered_description": "<p>Located in the United Kingdom</p>",
|
|
"date_created": 1691057093,
|
|
"creator_id": 8,
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 1,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
},
|
|
{
|
|
"name": "Denmark",
|
|
"stream_id": 1,
|
|
"is_archived": false,
|
|
"description": "A Scandinavian country",
|
|
"rendered_description": "<p>A Scandinavian country</p>",
|
|
"date_created": 1691057093,
|
|
"creator_id": null,
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 4,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
},
|
|
{
|
|
"name": "Verona",
|
|
"stream_id": 5,
|
|
"is_archived": false,
|
|
"description": "A city in Italy",
|
|
"rendered_description": "<p>A city in Italy</p>",
|
|
"date_created": 1691057093,
|
|
"creator_id": 9,
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 6,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
default channels in the organization are changed by an
|
|
organization administrator.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- default_streams
|
|
default_streams:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary
|
|
contains details about a single default channel.
|
|
items:
|
|
$ref: "#/components/schemas/DefaultChannel"
|
|
example:
|
|
{
|
|
"type": "default_streams",
|
|
"default_streams":
|
|
[
|
|
{
|
|
"name": "Scotland",
|
|
"stream_id": 3,
|
|
"is_archived": false,
|
|
"description": "Located in the United Kingdom",
|
|
"rendered_description": "<p>Located in the United Kingdom</p>",
|
|
"date_created": 1691057093,
|
|
"creator_id": 8,
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 1,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group": 2,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a message has been deleted.
|
|
|
|
Sent to all users who currently are subscribed to the
|
|
messages' recipient. May also be sent to additional users
|
|
who had access to it, including, in particular, an
|
|
administrator user deleting messages in a stream that they
|
|
are not subscribed to.
|
|
|
|
This means that clients can assume that they will always
|
|
receive an event of this type for deletions that the
|
|
client itself initiated.
|
|
|
|
This event is also sent when the user loses access to a message,
|
|
such as when it is [moved to a channel][message-move-channel] that
|
|
the user does not [have permission to access][channel-access].
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 274), this
|
|
event was only sent to subscribers of the message's recipient.
|
|
|
|
Before Zulip 5.0 (feature level 77), events
|
|
for direct messages contained additional `sender_id` and
|
|
`recipient_id` fields.
|
|
|
|
[message-move-channel]: /help/move-content-to-another-channel
|
|
[channel-access]: /help/channel-permissions
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- delete_message
|
|
message_ids:
|
|
type: array
|
|
description: |
|
|
Only present for clients that support the `bulk_message_deletion`
|
|
[client capability][client-capabilities].
|
|
|
|
A list containing the IDs of the newly deleted messages.
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
items:
|
|
type: integer
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
Only present for clients that do not support the `bulk_message_deletion`
|
|
[client capability][client-capabilities].
|
|
|
|
The ID of the newly deleted message.
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
The type of message. Either `"stream"` or `"private"`.
|
|
enum:
|
|
- private
|
|
- stream
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The ID of the channel to which the message was sent.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The topic to which the message was sent.
|
|
example:
|
|
{
|
|
"type": "delete_message",
|
|
"message_type": "private",
|
|
"message_id": 37,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of
|
|
configured muted topics have changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- muted_topics
|
|
muted_topics:
|
|
type: array
|
|
deprecated: true
|
|
description: |
|
|
Array of tuples, where each tuple describes a muted topic.
|
|
The first element of the tuple is the channel name in which the topic
|
|
has to be muted, the second element is the topic name to be muted
|
|
and the third element is an integer UNIX timestamp representing
|
|
when the topic was muted.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level
|
|
134). Starting with this version, clients that explicitly
|
|
requested the replacement `user_topic` event type when
|
|
registering their event queue will not receive this legacy
|
|
event type.
|
|
|
|
Before Zulip 3.0 (feature level 1), the `muted_topics`
|
|
array objects were 2-item tuples and did not include the timestamp
|
|
information for when the topic was muted.
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "muted_topics",
|
|
"muted_topics":
|
|
[["Denmark", "topic", 1594825442]],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when the user mutes/unmutes
|
|
a topic, or otherwise modifies their personal per-topic
|
|
configuration.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 134). Previously,
|
|
clients were notified about changes in muted topic
|
|
configuration via the `muted_topics` event type.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_topic
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which the topic belongs.
|
|
topic_name:
|
|
type: string
|
|
description: |
|
|
The name of the topic.
|
|
last_updated:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user-topic
|
|
relationship was last changed.
|
|
visibility_policy:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the user's visibility
|
|
preferences for the topic, such as whether the topic
|
|
is muted.
|
|
|
|
- 0 = None. Used to indicate that the user no
|
|
longer has a special visibility policy for this topic.
|
|
- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).
|
|
- 2 = Unmuted. Used to record unmuted topics.
|
|
- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 219), added followed as
|
|
a visibility policy option.
|
|
|
|
In Zulip 7.0 (feature level 170), added unmuted as a visibility
|
|
policy option.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"id": 1,
|
|
"type": "user_topic",
|
|
"stream_id": 1,
|
|
"topic_name": "topic",
|
|
"last_updated": 1594825442,
|
|
"visibility_policy": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of
|
|
configured [muted users](/api/mute-user) have changed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- muted_users
|
|
muted_users:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary describes
|
|
a muted user.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and timestamp of a muted user.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the muted user.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user was muted.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "muted_users",
|
|
"muted_users":
|
|
[
|
|
{"id": 1, "timestamp": 1594825442},
|
|
{"id": 22, "timestamp": 1654865392},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Heartbeat events are sent by the server to avoid
|
|
longpolling connections being affected by networks that
|
|
kill idle HTTP connections.
|
|
|
|
Clients do not need to do anything to process these
|
|
events, beyond the common `last_event_id` accounting.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- heartbeat
|
|
example: {"type": "heartbeat", "id": 0}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when the set of onboarding steps to show for the current user
|
|
has changed (e.g. because the user dismissed one).
|
|
|
|
Clients that feature a similar tutorial experience to the Zulip web app
|
|
may want to handle these events.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 233), this event was named
|
|
`hotspots`. Prior to this feature level, one-time notice onboarding
|
|
steps were not supported.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- onboarding_steps
|
|
onboarding_steps:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains details about a
|
|
single onboarding step.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
|
|
`hotspots`. Prior to this feature level, one-time notice onboarding
|
|
steps were not supported, and the `type` field in these objects did not
|
|
exist as all onboarding steps were implicitly hotspots.
|
|
items:
|
|
$ref: "#/components/schemas/OnboardingStep"
|
|
example:
|
|
{
|
|
"type": "onboarding_steps",
|
|
"onboarding_steps":
|
|
[
|
|
{
|
|
"type": "one_time_notice",
|
|
"name": "visibility_policy_banner",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a message's content, topic and/or
|
|
channel has been edited or when a message's content
|
|
has a rendering update, such as for an
|
|
[inline URL preview][inline-url-previews].
|
|
Sent to all users who had received the original
|
|
message.
|
|
|
|
[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 284), removed the
|
|
`prev_rendered_content_version` field as it is an internal
|
|
server implementation detail not used by any client.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
|
|
Is `null` when event is for a rendering update of the original message,
|
|
such as for an [inline URL preview][inline-url-previews].
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 114), this field
|
|
is present for all `update_message` events. Previously, this
|
|
field was omitted for [inline URL preview][inline-url-previews]
|
|
updates.
|
|
rendering_only:
|
|
type: boolean
|
|
description: |
|
|
Whether the event only updates the rendered content of the message.
|
|
|
|
This field should be used by clients to determine if the event
|
|
only provides a rendering update to the message content,
|
|
such as for an [inline URL preview][inline-url-previews].
|
|
When `true`, the event does not reflect a user-generated edit
|
|
and does not modify the message history.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 114). Clients can
|
|
correctly identify these rendering update event with earlier
|
|
Zulip versions by checking whether the `user_id` field was omitted.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message which was edited or updated.
|
|
|
|
This field should be used to apply content edits to the client's
|
|
cached message history, or to apply rendered content updates.
|
|
|
|
If the channel or topic was changed, the set of moved messages is
|
|
encoded in the separate `message_ids` field, which is guaranteed
|
|
to include `message_id`.
|
|
message_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
The list of IDs of messages to which any channel or topic changes
|
|
encoded in this event should be applied.
|
|
|
|
This list always includes `message_id`, even when there are no
|
|
channel or topic changes to apply.
|
|
|
|
These messages are guaranteed to have all been previously sent
|
|
to channel `stream_id` with topic `orig_subject`, and have been
|
|
moved to `new_stream_id` with topic `subject` (if those fields
|
|
are present in the event).
|
|
|
|
Clients processing these events should update all cached message
|
|
history associated with the moved messages (including adjusting
|
|
`unread_msgs` data structures, where the client may not have the
|
|
message itself in its history) to reflect the new channel and
|
|
topic.
|
|
|
|
Content changes should be applied only to the single message
|
|
indicated by `message_id`.
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's personal [message flags][message-flags] for the
|
|
message with ID `message_id` following the edit.
|
|
|
|
A client application should compare these to the original flags
|
|
to identify cases where a mention or alert word was added by the
|
|
edit.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
|
|
flag was deprecated in favor of the `stream_wildcard_mentioned` and
|
|
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
|
|
for backwards compatibility with older clients and equals
|
|
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
|
|
supporting older server versions should treat this field as a previous
|
|
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
|
|
were not available prior to this feature level.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The time when this message edit operation was processed by the
|
|
server.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 114), this field
|
|
is present for all `update_message` events. Previously, this
|
|
field was omitted for [inline URL preview][inline-url-previews]
|
|
updates.
|
|
stream_name:
|
|
type: string
|
|
description: |
|
|
Only present if the message was edited and originally sent to a channel.
|
|
|
|
The name of the channel that the message was sent to. Clients
|
|
are recommended to use the `stream_id` field instead.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if the message was edited and originally sent to a channel.
|
|
|
|
The pre-edit channel for all of the messages with IDs in
|
|
`message_ids`.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 112), this field
|
|
is present for all edits to a channel message. Previously, it
|
|
was not present when only the content of the channel message was
|
|
edited.
|
|
new_stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if message(s) were moved to a different channel.
|
|
|
|
The post-edit channel for all of the messages with IDs in
|
|
`message_ids`.
|
|
propagate_mode:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic and/or channel.
|
|
|
|
The choice the editing user made about which messages should be
|
|
affected by a channel/topic edit:
|
|
|
|
- `"change_one"`: Just change the one indicated in `message_id`.
|
|
- `"change_later"`: Change messages in the same topic that had
|
|
been sent after this one.
|
|
- `"change_all"`: Change all messages in that topic.
|
|
|
|
This parameter should be used to decide whether to change
|
|
navigation and compose box state in response to the edit. For
|
|
example, if the user was previously in topic narrow, and the
|
|
topic was edited with `"change_later"` or `"change_all"`, the Zulip
|
|
web app will automatically navigate to the new topic narrow.
|
|
Similarly, a message being composed to the old topic should
|
|
have its recipient changed to the new topic.
|
|
|
|
This navigation makes it much more convenient to move content
|
|
between topics without disruption or messages continuing
|
|
to be sent to the pre-edit topic by accident.
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
orig_subject:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic and/or channel.
|
|
|
|
The pre-edit topic for all of the messages with IDs in
|
|
`message_ids`.
|
|
subject:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different topic;
|
|
this field will not be present when moving messages to the same
|
|
topic name in a different channel.
|
|
|
|
The post-edit topic for all of the messages with IDs in
|
|
`message_ids`.
|
|
topic_links:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: |
|
|
The original link text present in the topic.
|
|
url:
|
|
type: string
|
|
description: |
|
|
The expanded target url which the link points to.
|
|
description: |
|
|
Only present if this event moved messages to a different topic;
|
|
this field will not be present when moving messages to the same
|
|
topic name in a different channel.
|
|
|
|
Data on any links to be included in the `topic`
|
|
line (these are generated by
|
|
[custom linkification filter](/help/add-a-custom-linkifier)
|
|
that match content in the message's topic.), corresponding
|
|
to the post-edit topic.
|
|
|
|
**Changes**: This field contained a list of urls before
|
|
Zulip 4.0 (feature level 46).
|
|
|
|
New in Zulip 3.0 (feature level 1). Previously, this field
|
|
was called `subject_links`; clients are recommended to
|
|
rename `subject_links` to `topic_links` if present for
|
|
compatibility with older Zulip servers.
|
|
orig_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
The original content of the message with ID `message_id`
|
|
immediately prior to this edit, in the original markdown.
|
|
orig_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
The original content of the message with ID `message_id`
|
|
immediately prior to this edit, rendered as HTML.
|
|
content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content or
|
|
updated the message content for an
|
|
[inline URL preview][inline-url-previews].
|
|
|
|
The new content of the message with ID `message_id`, in the
|
|
original Markdown.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content or
|
|
updated the message content for an
|
|
[inline URL preview][inline-url-previews].
|
|
|
|
The new content of the message with ID `message_id`,
|
|
rendered in HTML.
|
|
is_me_message:
|
|
type: boolean
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
Whether the message with ID `message_id` is now a
|
|
[/me status message][status-messages].
|
|
|
|
[status-messages]: /help/format-your-message-using-markdown#status-messages
|
|
required:
|
|
- type
|
|
- id
|
|
- user_id
|
|
- message_id
|
|
- message_ids
|
|
- flags
|
|
- edit_timestamp
|
|
- rendering_only
|
|
example:
|
|
{
|
|
"type": "update_message",
|
|
"user_id": 10,
|
|
"edit_timestamp": 1594825451,
|
|
"message_id": 58,
|
|
"stream_name": "Verona",
|
|
"orig_content": "hello",
|
|
"orig_rendered_content": "<p>hello</p>",
|
|
"content": "new content",
|
|
"rendered_content": "<p>new content</p>",
|
|
"is_me_message": false,
|
|
"propagate_mode": "change_all",
|
|
"stream_id": 5,
|
|
"orig_subject": "test",
|
|
"subject": "new_topic",
|
|
"topic_links": [],
|
|
"message_ids": [58, 57],
|
|
"flags": [],
|
|
"rendering_only": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user starts typing a message.
|
|
|
|
Sent to all clients for users who would receive the
|
|
message being typed, with the additional rule that typing
|
|
notifications for channel messages are only sent to clients
|
|
that included `stream_typing_notifications` in their
|
|
[client capabilities][client-capabilities] when registering
|
|
the event queue.
|
|
|
|
See [POST /typing](/api/set-typing-status) endpoint for more details.
|
|
|
|
**Changes**: Typing notifications for channel messages are new in
|
|
Zulip 4.0 (feature level 58).
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- typing
|
|
op:
|
|
type: string
|
|
enum:
|
|
- start
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
Type of message being composed. Must be `"stream"` or `"direct"`.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 215), replaced the
|
|
value `"private"` with `"direct"`.
|
|
|
|
New in Zulip 4.0 (feature level 58). Previously, all typing
|
|
notifications were implicitly direct messages.
|
|
enum:
|
|
- direct
|
|
- stream
|
|
sender:
|
|
additionalProperties: false
|
|
type: object
|
|
description: |
|
|
Object describing the user who is typing the message.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
recipients:
|
|
type: array
|
|
description: |
|
|
Only present if `message_type` is `"direct"`.
|
|
|
|
Array of dictionaries describing the set of users who would be
|
|
recipients of the message being typed. Each dictionary contains
|
|
details about one of the recipients. The sending user is guaranteed
|
|
to appear among the recipients.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and Zulip API email of a recipient.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The unique ID of the channel to which message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for direct messages.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
Topic within the channel where the message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for direct messages.
|
|
example:
|
|
{
|
|
"type": "typing",
|
|
"op": "start",
|
|
"message_type": "direct",
|
|
"sender":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
"recipients":
|
|
[
|
|
{
|
|
"user_id": 8,
|
|
"email": "user8@zulip.testserver",
|
|
},
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user stops typing a message.
|
|
|
|
Sent to all clients for users who would receive the message
|
|
that was previously being typed, with the additional rule
|
|
that typing notifications for channel messages are only sent to
|
|
clients that included `stream_typing_notifications` in their
|
|
[client capabilities][client-capabilities] when registering
|
|
the event queue.
|
|
|
|
See [POST /typing](/api/set-typing-status) endpoint for more details.
|
|
|
|
**Changes**: Typing notifications for channel messages are new in
|
|
Zulip 4.0 (feature level 58).
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- typing
|
|
op:
|
|
type: string
|
|
enum:
|
|
- stop
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
Type of message being composed. Must be `"stream"` or `"direct"`.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 215), replaced the
|
|
value `"private"` with `"direct"`.
|
|
|
|
New in Zulip 4.0 (feature level 58). Previously all typing
|
|
notifications were implicitly direct messages.
|
|
enum:
|
|
- direct
|
|
- stream
|
|
sender:
|
|
additionalProperties: false
|
|
type: object
|
|
description: |
|
|
Object describing the user who was previously typing the message.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
recipients:
|
|
type: array
|
|
description: |
|
|
Only present if `message_type` is `"direct"`.
|
|
|
|
Array of dictionaries describing the set of users who would be
|
|
recipients of the message that was previously being typed. Each
|
|
dictionary contains details about one of the recipients. The
|
|
sending user is guaranteed to appear among the recipients.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and email of a recipient.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The unique ID of the channel to which message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for direct messages.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
Topic within the channel where the message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for direct messages.
|
|
example:
|
|
{
|
|
"type": "typing",
|
|
"op": "stop",
|
|
"message_type": "direct",
|
|
"sender":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
"recipients":
|
|
[
|
|
{
|
|
"user_id": 8,
|
|
"email": "user8@zulip.testserver",
|
|
},
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user when [message flags][message-flags] are added
|
|
to messages.
|
|
|
|
This can reflect a direct user action, or can be the indirect
|
|
consequence of another action. Whatever the cause, if there's a change
|
|
in the set of message flags that the user has for a message, then an
|
|
`update_message_flags` event will be sent with the change. Note
|
|
that this applies when the user already had access to the message, and
|
|
continues to have access to it. When a message newly appears or
|
|
disappears, a [`message`][message-event] or
|
|
[`delete_message`][message-delete] event is sent instead.
|
|
|
|
Some examples of actions that trigger an `update_message_flags`
|
|
event:
|
|
|
|
- The `"starred"` flag is added when the user chooses to [star a
|
|
message](/help/star-a-message).
|
|
- The `"read"` flag is added when the user marks messages as read by
|
|
scrolling through them, or uses [Mark all messages as read][all-read]
|
|
on a conversation.
|
|
- The `"read"` flag is added when the user [mutes](/help/mute-a-user) a
|
|
message's sender.
|
|
- The `"read"` flag is added after the user unsubscribes from a channel,
|
|
or messages are moved to a not-subscribed channel, provided the user
|
|
can still access the messages at all. Note a
|
|
[`delete_message`][message-delete] event is sent in the case where the
|
|
user can no longer access the messages.
|
|
|
|
In some cases, a change in message flags that's caused by another change
|
|
may happen a short while after the original change, rather than
|
|
simultaneously. For example, when messages that were unread are moved to
|
|
a channel where the user is not subscribed, the resulting change in
|
|
message flags (and the corresponding `update_message_flags` event with
|
|
flag `"read"`) may happen later than the message move itself. The delay
|
|
in that example is typically at most a few hundred milliseconds and can
|
|
in rare cases be minutes or longer.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
[message-event]: /api/get-events#message
|
|
[message-delete]: /api/get-events#delete_message
|
|
[all-read]: /help/marking-messages-as-read#mark-all-messages-as-read
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message_flags
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
operation:
|
|
deprecated: true
|
|
description: |
|
|
Old name for the `op` field in this event type.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 32), and
|
|
replaced by the `op` field.
|
|
type: string
|
|
enum:
|
|
- add
|
|
flag:
|
|
type: string
|
|
description: |
|
|
The [flag][message-flags] that was added.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of all messages to which
|
|
the flag was added.
|
|
items:
|
|
type: integer
|
|
all:
|
|
type: boolean
|
|
description: |
|
|
Whether the specified flag was added to all messages.
|
|
This field is only relevant for the `"read"` flag, and
|
|
will be `false` for all other flags.
|
|
|
|
When `true` for the `"read"` flag, then the `messages`
|
|
array will be empty.
|
|
example:
|
|
{
|
|
"type": "update_message_flags",
|
|
"op": "add",
|
|
"operation": "add",
|
|
"flag": "starred",
|
|
"messages": [63],
|
|
"all": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user when [message flags][message-flags] are
|
|
removed from messages.
|
|
|
|
See the description for the [`update_message_flags` op:
|
|
`add`](/api/get-events#update_message_flags-add) event for
|
|
more details about these events.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message_flags
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
operation:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Old name for the `op` field in this event type.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 32), and
|
|
replaced by the `op` field.
|
|
enum:
|
|
- remove
|
|
flag:
|
|
type: string
|
|
description: |
|
|
The [flag][message-flags] to be removed.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of the messages from which the flag
|
|
was removed.
|
|
items:
|
|
type: integer
|
|
all:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Will be `false` for all specified flags.
|
|
|
|
**Deprecated** and will be removed in a future release.
|
|
message_details:
|
|
description: |
|
|
Only present if the specified `flag` is `"read"`.
|
|
|
|
A set of data structures describing the messages that
|
|
are being marked as unread with additional details to
|
|
allow clients to update the `unread_msgs` data
|
|
structure for these messages (which may not be
|
|
otherwise known to the client).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 121). Previously,
|
|
marking already read messages as unread was not
|
|
supported by the Zulip API.
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{message_id}`: Object containing details about the
|
|
message with the specified ID.
|
|
additionalProperties: false
|
|
required: ["type"]
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of this message. Either `"stream"` or `"private"`.
|
|
enum:
|
|
- private
|
|
- stream
|
|
mentioned:
|
|
type: boolean
|
|
description: |
|
|
A flag which indicates whether the message contains a mention
|
|
of the user.
|
|
|
|
Present only if the message mentions the current user.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Present only if `type` is `private`.
|
|
|
|
The user IDs of every recipient of this direct message, excluding yourself.
|
|
Will be the empty list for a message you had sent to only yourself.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Present only if `type` is `"stream"`.
|
|
|
|
The ID of the channel where the message was sent.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Present only if `type` is `"stream"`.
|
|
|
|
Name of the topic where the message was sent.
|
|
unmuted_stream_msg:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated** internal implementation detail. Clients should
|
|
ignore this field as it will be removed in the future.
|
|
example:
|
|
{
|
|
"type": "update_message_flags",
|
|
"op": "remove",
|
|
"operation": "remove",
|
|
"flag": "starred",
|
|
"messages": [63],
|
|
"message_details":
|
|
{
|
|
"63":
|
|
{
|
|
"type": "stream",
|
|
"stream_id": 22,
|
|
"topic": "lunch",
|
|
},
|
|
},
|
|
"all": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to users in an organization when a [user group](/help/user-groups) is created.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
group:
|
|
$ref: "#/components/schemas/UserGroup"
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add",
|
|
"group":
|
|
{
|
|
"name": "backend",
|
|
"members": [12],
|
|
"creator_id": 9,
|
|
"date_created": 1717484476,
|
|
"description": "Backend team",
|
|
"id": 2,
|
|
"is_system_group": false,
|
|
"can_add_members_group": 16,
|
|
"can_join_group": 16,
|
|
"can_leave_group": 15,
|
|
"can_manage_group": 16,
|
|
"can_mention_group": 11,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization
|
|
when a property of a user group is changed.
|
|
|
|
For group deactivation, this event is only sent
|
|
if `include_deactivated_groups` client capability
|
|
is set to `true`.
|
|
|
|
This event is also sent when deactivating or reactivating
|
|
a user for settings set to anonymous user groups which the
|
|
user is direct member of. When deactivating the user, event
|
|
is only sent to users who cannot access the deactivated user.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 303), this
|
|
event can also be sent when deactivating or reactivating a user.
|
|
|
|
Prior to Zulip 10.0 (feature level 294), this event was sent to
|
|
all clients when a user group was deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
data:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing the changed details of the user group.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The new name of the user group. Only present if the group's name changed.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The new description of the group. Only present if the description
|
|
changed.
|
|
can_add_members_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to add members to this group. Only present if this user
|
|
group permission setting changed.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 305). Previously, this
|
|
permission was controlled by the `can_manage_group` setting.
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_join_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to join this group. Only present if this user group
|
|
permission setting changed.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 301).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_leave_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to leave this group. Only present if this user group
|
|
permission setting changed.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 308).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_manage_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [manage this group][manage-user-groups]. Only present
|
|
if this user group permission setting changed.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 283).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[manage-user-groups]: /help/manage-user-groups
|
|
can_mention_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [mention this user group][mentions]. Only present
|
|
if this user group permission setting changed.
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
|
|
always the integer form of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 8.0 (feature level 198), this setting was named
|
|
`can_mention_group_id`.
|
|
|
|
New in Zulip 8.0 (feature level 191). Previously, groups could be
|
|
mentioned only if they were not [system groups][system-groups].
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[mentions]: /help/mention-a-user-or-group
|
|
deactivated:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is deactivated. Deactivated groups
|
|
cannot be used as a subgroup of another group or used for
|
|
any other purpose.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 290).
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "update",
|
|
"group_id": 2,
|
|
"data":
|
|
{
|
|
"description": "Mention this group to get the security team's attention.",
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when users have been added to a user group.
|
|
|
|
This event is also sent when reactivating a user for all the user
|
|
groups the reactivated user was a member of before being deactivated.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 303), this
|
|
event can also be sent when reactivating a user.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add_members
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group with new members.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the users who have been added
|
|
to the user group.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add_members",
|
|
"group_id": 2,
|
|
"user_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when users have been removed from
|
|
a user group.
|
|
|
|
This event is also sent when deactivating a user, for all
|
|
the user groups the deactivated user is a member of, but only
|
|
to the users who cannot access the deactivated user.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 303),
|
|
this event can also be sent when deactivating a user.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove_members
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the users who have been removed
|
|
from the user group.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove_members",
|
|
"group_id": 2,
|
|
"user_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when subgroups have been added to
|
|
a user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add_subgroups
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the subgroups that have been added
|
|
to the user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Previously, this was called `subgroup_ids`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add_subgroups",
|
|
"group_id": 2,
|
|
"direct_subgroup_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when subgroups have been removed from
|
|
a user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove_subgroups
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the subgroups that have been
|
|
removed from the user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Previously, this was called `subgroup_ids`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove_subgroups",
|
|
"group_id": 2,
|
|
"direct_subgroup_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user group is deactivated but only to clients
|
|
with `include_deactivated_groups` client capability set to `false`.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 294), this
|
|
event was sent when a user group was deleted.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the group which has been deleted.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove",
|
|
"group_id": 2,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
set of configured [linkifiers](/help/add-a-custom-linkifier)
|
|
for the organization has changed.
|
|
|
|
Processing this event is important for doing Markdown local echo
|
|
correctly.
|
|
|
|
Clients will not receive this event unless the event queue is
|
|
registered with the client capability
|
|
`{"linkifier_url_template": true}`.
|
|
See [`POST /register`](/api/register-queue#parameter-client_capabilities)
|
|
for how client capabilities can be specified.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 176), the
|
|
`linkifier_url_template` client capability was not required. The
|
|
requirement was added because linkifiers were updated to contain
|
|
a URL template instead of a URL format string, which was not a
|
|
backwards-compatible change.
|
|
|
|
New in Zulip 4.0 (feature level 54), replacing the deprecated
|
|
`realm_filters` event type.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_linkifiers
|
|
realm_linkifiers:
|
|
type: array
|
|
description: |
|
|
An ordered array of dictionaries where each dictionary contains
|
|
details about a single linkifier.
|
|
|
|
Clients should always process linkifiers in the order given;
|
|
this is important if the realm has linkifiers with overlapping
|
|
patterns. The order can be modified using [`PATCH
|
|
/realm/linkifiers`](/api/reorder-linkifiers).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
|
|
that represents the pattern that should be linkified by this linkifier.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
|
|
URL template to be used for linkifying matches.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
example:
|
|
{
|
|
"type": "realm_linkifiers",
|
|
"realm_linkifiers":
|
|
[
|
|
{
|
|
"pattern": "#(?P<id>[123])",
|
|
"url_template": "https://realm.com/my_realm_filter/{id}",
|
|
"id": 1,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Legacy event type that is no longer sent to clients. Previously, sent
|
|
to all users in a Zulip organization when the set of configured
|
|
[linkifiers](/help/add-a-custom-linkifier) for the organization was
|
|
changed.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 176), this event type
|
|
was sent to clients.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 54), and replaced by the
|
|
`realm_linkifiers` event type, which has a clearer name and format.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_filters
|
|
realm_filters:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
description: |
|
|
An array of tuples, where each tuple described a linkifier. The first
|
|
element of the tuple was a string regex pattern which represented the
|
|
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
|
|
The second element was the URL format string that the pattern should be
|
|
linkified with. A URL format string for the above example would be
|
|
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
|
|
was the ID of the realm filter.
|
|
example:
|
|
{
|
|
"type": "realm_filters",
|
|
"realm_filters": [],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
set of configured [code playgrounds](/help/code-blocks#code-playgrounds)
|
|
for the organization has changed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_playgrounds
|
|
realm_playgrounds:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
data about a single playground entry.
|
|
items:
|
|
$ref: "#/components/schemas/RealmPlayground"
|
|
example:
|
|
{
|
|
"type": "realm_playgrounds",
|
|
"realm_playgrounds":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Python playground",
|
|
"pygments_language": "Python",
|
|
"url_template": "https://python.example.com",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when
|
|
a [custom emoji](/help/custom-emoji) has been updated,
|
|
typically when a new emoji has been added or an old one
|
|
has been deactivated. The event contains all custom emoji
|
|
configured for the organization, not just the updated
|
|
custom emoji.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_emoji
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
realm_emoji:
|
|
type: object
|
|
description: |
|
|
An object in which each key describes a realm emoji.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
example:
|
|
{
|
|
"type": "realm_emoji",
|
|
"op": "update",
|
|
"realm_emoji":
|
|
{
|
|
"2":
|
|
{
|
|
"id": "2",
|
|
"name": "my_emoji",
|
|
"source_url": "/user_avatars/2/emoji/images/2.png",
|
|
"deactivated": true,
|
|
"author_id": 11,
|
|
},
|
|
"1":
|
|
{
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/2/emoji/images/1.png",
|
|
"deactivated": false,
|
|
"author_id": 11,
|
|
},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
realm_domain:
|
|
$ref: "#/components/schemas/RealmDomain"
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "add",
|
|
"realm_domain":
|
|
{
|
|
"domain": "zulip.org",
|
|
"allow_subdomains": false,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- change
|
|
realm_domain:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the edited domain.
|
|
properties:
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The domain whose settings have changed.
|
|
allow_subdomains:
|
|
type: boolean
|
|
description: |
|
|
Whether subdomains are allowed for this domain.
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "change",
|
|
"realm_domain":
|
|
{
|
|
"domain": "zulip.org",
|
|
"allow_subdomains": true,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The domain to be removed.
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "remove",
|
|
"domain": "zulip.org",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to the user who requested a
|
|
[data export](/help/export-your-organization)
|
|
when the status of the data export changes.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_export
|
|
exports:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details about a data export of the organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 304), `export_type`
|
|
parameter was not present as only public data export was supported via API.
|
|
items:
|
|
$ref: "#/components/schemas/RealmExport"
|
|
example:
|
|
{
|
|
"type": "realm_export",
|
|
"exports":
|
|
[
|
|
{
|
|
"id": 107,
|
|
"export_time": 1594825443.6567969322,
|
|
"acting_user_id": 10,
|
|
"export_url": null,
|
|
"deleted_timestamp": null,
|
|
"failed_timestamp": 1594825444.4363360405,
|
|
"pending": false,
|
|
"export_type": 1,
|
|
},
|
|
],
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to administrators when the [data export
|
|
consent][help-export-consent] status for a user changes, whether due
|
|
to a user changing their consent preferences or a user being created
|
|
or reactivated (since user creation/activation events do not contain
|
|
these data).
|
|
|
|
[help-export-consent]: /help/export-your-organization#configure-whether-administrators-can-export-your-private-data
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 312). Previously,
|
|
there was not event available to administrators with these data.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_export_consent
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user whose setting was changed.
|
|
consented:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has consented for their private data export.
|
|
example:
|
|
{
|
|
"type": "realm_export_consent",
|
|
"user_id": 1,
|
|
"consented": true,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to users who can administer a newly created bot
|
|
user. Clients will also receive a `realm_user` event that
|
|
contains basic details (but not the API key).
|
|
|
|
The `realm_user` events are sufficient for clients that
|
|
only need to interact with the bot; this `realm_bot` event
|
|
type is relevant only for administering bots.
|
|
|
|
Only organization administrators and the user who owns the bot will
|
|
receive this event.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
bot:
|
|
$ref: "#/components/schemas/Bot"
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "add",
|
|
"bot":
|
|
{
|
|
"email": "test-bot@zulip.testserver",
|
|
"user_id": 36,
|
|
"full_name": "Foo Bot",
|
|
"bot_type": 1,
|
|
"is_active": true,
|
|
"api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
|
|
"default_sending_stream": null,
|
|
"default_events_register_stream": null,
|
|
"default_all_public_streams": false,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
|
|
"services": [],
|
|
"owner_id": 10,
|
|
},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to users who can administer a bot user when the bot is
|
|
configured. Clients may also receive a `realm_user` event that
|
|
for changes in public data about the bot (name, etc.).
|
|
|
|
The `realm_user` events are sufficient for clients that
|
|
only need to interact with the bot; this `realm_bot` event
|
|
type is relevant only for administering bots.
|
|
|
|
Only organization administrators and the user who owns the bot will
|
|
receive this event.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
bot:
|
|
allOf:
|
|
- description: |
|
|
Object containing details about the changed bot.
|
|
It contains two properties: the user ID of the bot and
|
|
the property to be changed. The changed property is one
|
|
of the remaining properties listed below.
|
|
- $ref: "#/components/schemas/BasicBot"
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "update",
|
|
"bot":
|
|
{
|
|
"user_id": 37,
|
|
"services":
|
|
[
|
|
{
|
|
"base_url": "http://hostname.domain2.com",
|
|
"interface": 2,
|
|
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw",
|
|
},
|
|
],
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when a bot has been deactivated.
|
|
|
|
**Changes**: Deprecated and no longer sent since Zulip 8.0 (feature level 222).
|
|
|
|
Previously, this event was sent to all users in a Zulip organization when a
|
|
bot was deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
bot:
|
|
type: object
|
|
description: |
|
|
Object containing details about the deactivated bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the deactivated bot.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the deactivated bot.
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "remove",
|
|
"bot":
|
|
{"user_id": 35, "full_name": "Foo Bot"},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when a bot has been deactivated.
|
|
Note that this is very similar to the bot_remove event
|
|
and one of them will be removed soon.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- delete
|
|
bot:
|
|
type: object
|
|
description: |
|
|
Object containing details about the deactivated bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the deactivated bot.
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "delete",
|
|
"bot": {"user_id": 35},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
The simpler of two possible event types sent to all users
|
|
in a Zulip organization when the configuration of the
|
|
organization (realm) has changed.
|
|
|
|
Often individual settings are migrated from this format to
|
|
the [realm/update_dict](#realm-update_dict) event format when additional realm
|
|
settings are added whose values are coupled to each other
|
|
in some way. The specific values supported by this event
|
|
type are documented in the [realm/update_dict](#realm-update_dict)
|
|
documentation.
|
|
|
|
A correct client implementation should convert these
|
|
events into the corresponding [realm/update_dict](#realm-update_dict)
|
|
event and then process that.
|
|
|
|
**Changes**: Removed `extra_data` optional property in Zulip 10.0
|
|
(feature level 306). The `extra_data` used to include an
|
|
`upload_quota` field when changed property was `plan_type`. The
|
|
server now sends a standard `realm/update_dict` event for plan
|
|
changes.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
The name of the property that was changed.
|
|
value:
|
|
description: |
|
|
The new value of the property.
|
|
nullable: true
|
|
oneOf:
|
|
- type: string
|
|
- type: boolean
|
|
- type: integer
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "update",
|
|
"property": "disallow_disposable_email_addresses",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
organization (realm) is deactivated. Its main purpose is to
|
|
flush active longpolling connections so clients can immediately
|
|
show the organization as deactivated.
|
|
|
|
Clients cannot rely on receiving this event, because they will
|
|
no longer be able to authenticate to the Zulip API due to the
|
|
deactivation, and thus can miss it if they did not have an active
|
|
longpolling connection at the moment of deactivation.
|
|
|
|
Correct handling of realm deactivations requires that clients
|
|
parse authentication errors from GET /events; if that is done
|
|
correctly, the client can ignore this event type and rely on its
|
|
handling of the `GET /events` request it will do immediately
|
|
after processing this batch of events.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- deactivated
|
|
realm_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deactivated realm.
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "deactivated",
|
|
"realm_id": 2,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all the users whenever the Zulip server restarts.
|
|
|
|
Specifically, this event is sent whenever the Tornado process
|
|
for the user is restarted; in particular, this will always happen
|
|
when the Zulip server is upgraded.
|
|
|
|
Clients should use this event to update their tracking of the
|
|
server's capabilities, and to decide if they wish to get a new
|
|
event queue after a server upgrade. Clients doing so must
|
|
implement a random delay strategy to spread such restarts over 5
|
|
minutes or more to avoid creating a synchronized thundering herd
|
|
effect.
|
|
|
|
**Changes**: Removed the `immediate` flag, which was only used by
|
|
web clients in development, in Zulip 9.0 (feature level 240).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- restart
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The Zulip version number, in the format where this appears
|
|
in the [server_settings](/api/get-server-settings) and
|
|
[register](/api/register-queue) responses.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The Zulip merge base number, in the format where this appears
|
|
in the [server_settings](/api/get-server-settings) and
|
|
[register](/api/register-queue) responses.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
The [Zulip feature level](/api/changelog) of the server
|
|
after the restart.
|
|
|
|
Clients should use this to update their tracking of the
|
|
server's capabilities, and may choose to refetch their state
|
|
and create a new event queue when the API feature level has
|
|
changed in a way that the client finds significant. Clients
|
|
choosing to do so must implement a random delay strategy to
|
|
spread such restarts over 5 or more minutes to avoid creating
|
|
a synchronized thundering herd effect.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
server_generation:
|
|
type: integer
|
|
description: |
|
|
The timestamp at which the server started.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"id": 0,
|
|
"server_generation": 1619334181,
|
|
"type": "restart",
|
|
"zulip_feature_level": 57,
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
}
|
|
- type: object
|
|
description: |
|
|
An event which signals the official Zulip web/desktop app to update,
|
|
by reloading the page and fetching a new queue; this will generally
|
|
follow a `restart` event. Clients which do not obtain their code
|
|
from the server (e.g. mobile and terminal clients, which store their
|
|
code locally) should ignore this event.
|
|
|
|
Clients choosing to reload the application must implement a random
|
|
delay strategy to spread such restarts over 5 or more minutes to
|
|
avoid creating a synchronized thundering herd effect.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 240).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- web_reload_client
|
|
immediate:
|
|
type: boolean
|
|
description: |
|
|
Whether the client should fetch a new event queue immediately,
|
|
rather than using a backoff strategy to avoid thundering herds.
|
|
A Zulip development server uses this parameter to reload
|
|
clients immediately.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"id": 0,
|
|
"type": "web_reload_client",
|
|
"immediate": true,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
The more general of two event types that may be used when
|
|
sending an event to all users in a Zulip organization when
|
|
the configuration of the organization (realm) has changed.
|
|
|
|
Unlike the simpler [realm/update](#realm-update) event format, this
|
|
event type supports multiple properties being changed in a
|
|
single event.
|
|
|
|
This event is also sent when deactivating or reactivating a user
|
|
for settings set to anonymous user groups which the user is direct
|
|
member of. When deactivating the user, event is only sent to users
|
|
who cannot access the deactivated user.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 303), this
|
|
event can also be sent when deactivating or reactivating a user.
|
|
|
|
In Zulip 7.0 (feature level 163), the realm setting
|
|
`email_address_visibility` was removed. It was replaced by a [user
|
|
setting](/api/update-settings#parameter-email_address_visibility) with
|
|
a [realm user default][user-defaults], with the encoding of different
|
|
values preserved. Clients can support all versions by supporting the
|
|
current API and treating every user as having the realm's
|
|
`email_address_visibility` value.
|
|
|
|
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update_dict
|
|
property:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
Always `"default"`. Present for backwards-compatibility with older
|
|
clients that predate the `update_dict` event style.
|
|
|
|
**Deprecated** and will be removed in a future release.
|
|
data:
|
|
type: object
|
|
description: |
|
|
An object containing the properties that have changed.
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 316), `edit_topic_policy`
|
|
property was removed and replaced by `can_move_messages_between_topics_group`
|
|
realm setting.
|
|
|
|
In Zulip 7.0 (feature level 183), the
|
|
`community_topic_editing_limit_seconds` property was removed.
|
|
It was documented as potentially returned as a changed property
|
|
in this event, but in fact it was only ever returned in the
|
|
[`POST /register`](/api/register-queue) response.
|
|
|
|
Before Zulip 6.0 (feature level 150), on changing any of
|
|
`allow_message_editing`, `message_content_edit_limit_seconds`, or
|
|
`edit_topic_policy` settings, this object included all the three settings
|
|
irrespective of which of these settings were changed. Now, a separate event
|
|
is sent for each changed setting.
|
|
properties:
|
|
allow_edit_history:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization is configured to allow users to access
|
|
[message edit history](/help/view-a-messages-edit-history).
|
|
allow_message_editing:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization's [message edit policy][config-message-editing]
|
|
allows editing the content of messages.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
[config-message-editing]: /help/restrict-message-editing-and-deletion
|
|
authentication_methods:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmAuthenticationMethod"
|
|
description: |
|
|
Dictionary of authentication method keys mapped to dictionaries that
|
|
describe the properties of the named authentication method for the
|
|
organization - its enabled status and availability for use by the
|
|
organization.
|
|
|
|
Clients should use this to implement server-settings UI to change which
|
|
methods are enabled for the organization. For authentication UI itself,
|
|
clients should use the pre-authentication metadata returned by
|
|
[`GET /server_settings`](/api/get-server-settings).
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 243), the values in this
|
|
dictionary were changed. Previously, the values were a simple boolean
|
|
indicating whether the backend is enabled or not.
|
|
bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create bot users in this organization.
|
|
can_access_all_users_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the
|
|
set of users who are allowed to access all users in the
|
|
organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 314), this value used
|
|
to be of type integer and did not accept anonymous user groups.
|
|
|
|
New in Zulip 8.0 (feature level 225).
|
|
can_create_groups:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create user
|
|
groups in this organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 299). Previously
|
|
`user_group_edit_policy` field used to control the permission
|
|
to create user groups.
|
|
can_create_public_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create public
|
|
channels in this organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 264). Previously
|
|
`realm_create_public_stream_policy` field used to control the
|
|
permission to create public channels.
|
|
can_create_private_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create private
|
|
channels in this organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 266). Previously
|
|
`realm_create_private_stream_policy` field used to control the
|
|
permission to create private channels.
|
|
can_create_web_public_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create web-public
|
|
channels in this organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 280). Previously
|
|
`realm_create_web_public_stream_policy` field used to control
|
|
the permission to create web-public channels.
|
|
can_add_custom_emoji_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to add custom emoji in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 307). Previously, this
|
|
permission was controlled by the enum `add_custom_emoji_policy`. Values
|
|
were 1=Members, 2=Admins, 3=Full members, 4=Moderators.
|
|
|
|
Before Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`
|
|
boolean setting controlled this permission; `true` corresponded to `Admins`,
|
|
and `false` to `Everyone`.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
can_delete_any_message_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to delete any message in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 281). Previously, this
|
|
permission was limited to administrators only and was uneditable.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
can_delete_own_message_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to delete messages that they have sent in the
|
|
organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 291). Previously, this
|
|
permission was controlled by the enum `delete_own_message_policy`. Values
|
|
were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.
|
|
|
|
Before Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean
|
|
setting controlled this permission; `true` corresponded to `Everyone`, and
|
|
`false` to `Admins`.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
can_move_messages_between_channels_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to move messages from one channel to another
|
|
in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 310). Previously, this
|
|
permission was controlled by the enum `move_messages_between_streams_policy`.
|
|
Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.
|
|
|
|
In Zulip 7.0 (feature level 159), `Nobody` was added as an option to
|
|
`move_messages_between_streams_policy` enum.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
can_move_messages_between_topics_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to move messages from one topic to another
|
|
within a channel in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 316). Previously, this
|
|
permission was controlled by the enum `edit_topic_policy`. Values were
|
|
1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.
|
|
|
|
In Zulip 7.0 (feature level 159), `Nobody` was added as an option to
|
|
`edit_topic_policy` enum.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
can_manage_all_groups:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values)
|
|
defining the set of users who have permission to
|
|
administer all existing groups in this organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 305), only users who
|
|
were a member of the group or had the moderator role or above could
|
|
exercise the permission on a given group.
|
|
|
|
New in Zulip 10.0 (feature level 299). Previously the
|
|
`user_group_edit_policy` field controlled the permission
|
|
to manage user groups. Valid values were as follows:
|
|
|
|
- 1 = All members can create and edit user groups
|
|
- 2 = Only organization administrators can create and edit
|
|
user groups
|
|
- 3 = Only [full members][calc-full-member] can create and
|
|
edit user groups.
|
|
- 4 = Only organization administrators and moderators can
|
|
create and edit user groups.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
create_multiuse_invite_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the
|
|
set of users who are allowed to create [reusable invitation
|
|
links](/help/invite-new-users#create-a-reusable-invitation-link)
|
|
to the organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 314), this value used
|
|
to be of type integer and did not accept anonymous user groups.
|
|
|
|
New in Zulip 8.0 (feature level 209).
|
|
default_code_block_language:
|
|
type: string
|
|
description: |
|
|
The default pygments language code to be used for code blocks in this
|
|
organization. If an empty string, no default has been set.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant
|
|
that both `null` and an empty string could represent that no default was
|
|
set for this realm setting in the [`POST /register`](/api/register-queue)
|
|
response. The documentation for both that endpoint and this event
|
|
incorrectly stated that the only representation for no default language
|
|
was `null`. This event in fact uses the empty string to indicate that no
|
|
default has been set in all server versions.
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
The default language for the organization.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The description of the organization, used on login and registration pages.
|
|
digest_emails_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
|
|
digest_weekday:
|
|
type: integer
|
|
description: |
|
|
The day of the week when the organization will send
|
|
its weekly digest email to inactive users.
|
|
direct_message_initiator_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to start a new direct message conversation
|
|
involving other non-bot users. Users who are outside this group and attempt
|
|
to send the first direct message to a given collection of recipient users
|
|
will receive an error, unless all other recipients are bots or the sender.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 270).
|
|
|
|
Previously, access to send direct messages was controlled by the
|
|
`private_message_policy` realm setting, which supported values of
|
|
1 (enabled) and 2 (disabled).
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
direct_message_permission_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to fully use direct messages. Users outside
|
|
this group can only send direct messages to conversations where all the
|
|
recipients are in this group, are bots, or are the sender, ensuring that
|
|
every direct message conversation will be visible to at least one user in
|
|
this group.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 270).
|
|
|
|
Previously, access to send direct messages was controlled by the
|
|
`private_message_policy` realm setting, which supported values of
|
|
1 (enabled) and 2 (disabled).
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
disallow_disposable_email_addresses:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization disallows disposable email
|
|
addresses.
|
|
email_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Whether users are allowed to change their own email address in this
|
|
organization. This is typically disabled for organizations that
|
|
synchronize accounts from LDAP or a similar corporate database.
|
|
enable_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether read receipts is enabled in the organization or not.
|
|
|
|
If disabled, read receipt data will be unavailable to clients, regardless
|
|
of individual users' personal read receipt settings. See also the
|
|
`send_read_receipts` setting within `realm_user_settings_defaults`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
emails_restricted_to_domains:
|
|
type: boolean
|
|
description: |
|
|
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
this organization are required to have an email
|
|
address in one of the `realm_domains` configured for the organization.
|
|
enable_guest_user_indicator:
|
|
type: boolean
|
|
description: |
|
|
Whether clients should display "(guest)" after the names of
|
|
guest users to prominently highlight their status.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 216).
|
|
enable_spectator_access:
|
|
type: boolean
|
|
description: |
|
|
Whether web-public channels are enabled in this organization.
|
|
|
|
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
[server setting][server-settings] is enabled on the Zulip
|
|
server. See also the `can_create_web_public_channel_group`
|
|
realm setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 109).
|
|
giphy_rating:
|
|
type: integer
|
|
description: |
|
|
Maximum rating of the GIFs that will be retrieved from GIPHY.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 55).
|
|
icon_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's
|
|
[profile icon](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the organization's icon.
|
|
|
|
- "G" means generated by Gravatar (the default).
|
|
- "U" means uploaded by an organization administrator.
|
|
icon_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's [profile icon](/help/create-your-organization-profile).
|
|
inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization has been configured to enable
|
|
[previews of linked images](/help/image-video-and-website-previews).
|
|
inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization has been configured to enable
|
|
[previews of linked websites](/help/image-video-and-website-previews).
|
|
invite_required:
|
|
type: boolean
|
|
description: |
|
|
Whether an invitation is required to join this organization.
|
|
invite_to_realm_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can invite other users to join the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
|
|
previous `invite_by_admins_only` boolean.
|
|
invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can add other users to channels in this organization.
|
|
jitsi_server_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the custom Jitsi Meet server configured in this organization's
|
|
settings.
|
|
|
|
`null`, the default, means that the organization is using the should use the
|
|
server-level configuration, `server_jitsi_server_url`.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only
|
|
available as a server-level configuration, and required a server restart to
|
|
change.
|
|
logo_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's wide logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
mandatory_topics:
|
|
type: boolean
|
|
description: |
|
|
Whether [topics are required](/help/require-topics) for messages in this organization.
|
|
max_file_upload_size_mib:
|
|
type: integer
|
|
description: |
|
|
The new maximum file size that can be uploaded to this Zulip organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 306). Previously, this field of
|
|
the core state did not support being updated via the events system, as it was
|
|
typically hardcoded for a given Zulip installation.
|
|
message_content_allowed_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether notification emails in this organization are allowed to
|
|
contain Zulip the message content, or simply indicate that a new
|
|
message was sent.
|
|
message_content_delete_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be deleted
|
|
with this organization's
|
|
[message deletion policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be 0. A `null` value means no limit: messages can be deleted
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 5.0 (feature level 100).
|
|
message_content_edit_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be edited
|
|
with this organization's
|
|
[message edit policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be `0`. A `null` value means no limit, so messages can be edited
|
|
regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 138), no limit was
|
|
represented using the special value `0`.
|
|
move_messages_within_stream_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be moved within a
|
|
channel to another topic by users who have permission to do so based on this
|
|
organization's [topic edit policy](/help/restrict-moving-messages). This
|
|
setting does not affect moderators and administrators.
|
|
|
|
Will not be `0`. A `null` value means no limit, so message topics can be
|
|
edited regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
|
|
limit was always 72 hours for users who were not administrators or
|
|
moderators.
|
|
move_messages_between_streams_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be moved between
|
|
channels by users who have permission to do so based on this organization's
|
|
[message move policy](/help/restrict-moving-messages). This setting does
|
|
not affect moderators and administrators.
|
|
|
|
Will not be `0`. A `null` value means no limit, so messages can be moved
|
|
regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
|
|
no time limit for moving messages between channels for users with permission
|
|
to do so.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the organization, used in login pages etc.
|
|
name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their name
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
night_logo_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's dark theme
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
night_logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's dark theme wide-format logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
new_stream_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which automated messages announcing the
|
|
[creation of new channels][new-channel-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 241), renamed `notifications_stream_id`
|
|
to `new_stream_announcements_stream_id`.
|
|
org_type:
|
|
type: integer
|
|
description: |
|
|
The [organization type](/help/organization-type)
|
|
for the realm.
|
|
|
|
- 0 = Unspecified
|
|
- 10 = Business
|
|
- 20 = Open-source project
|
|
- 30 = Education (non-profit)
|
|
- 35 = Education (for-profit)
|
|
- 40 = Research
|
|
- 50 = Event or conference
|
|
- 60 = Non-profit (registered)
|
|
- 70 = Government
|
|
- 80 = Political group
|
|
- 90 = Community
|
|
- 100 = Personal
|
|
- 1000 = Other
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 128).
|
|
plan_type:
|
|
type: integer
|
|
description: |
|
|
The plan type of the organization.
|
|
|
|
- 1 = Self-hosted organization (SELF_HOSTED)
|
|
- 2 = Zulip Cloud free plan (LIMITED)
|
|
- 3 = Zulip Cloud Standard plan (STANDARD)
|
|
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
|
|
presence_disabled:
|
|
type: boolean
|
|
description: |
|
|
Whether online presence of other users is shown in this
|
|
organization.
|
|
push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether push notifications are enabled for this organization. Typically
|
|
`true` for Zulip Cloud and self-hosted realms that have a valid
|
|
registration for the [Mobile push notifications
|
|
service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),
|
|
and `false` for self-hosted servers that do not.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 231).
|
|
Previously, this value was never updated via events.
|
|
push_notifications_enabled_end_timestamp:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
If the server expects the realm's push notifications access to end at a
|
|
definite time in the future, the time at which this is expected to happen.
|
|
Mobile clients should use this field to display warnings to users when the
|
|
indicated timestamp is near.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 231).
|
|
require_unique_names:
|
|
type: boolean
|
|
description: |
|
|
Indicates whether the organization is configured to require users to have
|
|
unique full names. If true, the server will reject attempts to create a
|
|
new user, or change the name of an existing user, where doing so would
|
|
lead to two users whose names are identical modulo case and unicode
|
|
normalization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip
|
|
server could not be configured to enforce unique names.
|
|
send_welcome_emails:
|
|
type: boolean
|
|
description: |
|
|
Whether or not this organization is configured to send the standard Zulip
|
|
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
|
|
signup_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which automated messages announcing
|
|
that [new users have joined the organization][new-user-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-user-announce]: /help/configure-automated-notices#new-user-announcements
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 241), renamed
|
|
`signup_notifications_stream_id` to `signup_announcements_stream_id`.
|
|
upload_quota_mib:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The new upload quota for the Zulip organization.
|
|
|
|
If `null`, there is no limit.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 306). Previously,
|
|
this was present changed via an `upload_quota` field in `extra_data` property
|
|
of [realm/update](#realm-update) event format for `plan_type` events.
|
|
video_chat_provider:
|
|
type: integer
|
|
description: |
|
|
The configured [video call provider](/help/start-a-call) for the
|
|
organization.
|
|
|
|
- 0 = None
|
|
- 1 = Jitsi Meet
|
|
- 3 = Zoom
|
|
- 4 = BigBlueButton
|
|
|
|
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
|
|
to disable video call UI.
|
|
waiting_period_threshold:
|
|
type: integer
|
|
description: |
|
|
Members whose accounts have been created at least this many days ago
|
|
will be treated as [full members][calc-full-member]
|
|
for the purpose of settings that restrict access to new members.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
want_advertise_in_communities_directory:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has given permission to be advertised in the
|
|
Zulip [communities directory](/help/communities-directory).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 129).
|
|
wildcard_mention_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for who can use wildcard mentions in
|
|
large channels.
|
|
|
|
- 1 = Any user can use wildcard mentions in large channels.
|
|
- 2 = Only members can use wildcard mentions in large channels.
|
|
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.
|
|
- 5 = Only organization administrators can use wildcard mentions in large channels.
|
|
- 6 = Nobody can use wildcard mentions in large channels.
|
|
- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.
|
|
|
|
All users will receive a warning/reminder when using
|
|
mentions in large channels, even when permitted to do so.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
|
|
Zulip 4.0 (feature level 62). Channel administrators option removed in
|
|
Zulip 6.0 (feature level 133).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
zulip_update_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which automated messages announcing
|
|
new features or other end-user updates about the Zulip software are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 242).
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "update_dict",
|
|
"property": "default",
|
|
"data":
|
|
{"message_content_edit_limit_seconds": 600},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
[default settings for new users][new-user-defaults]
|
|
of the organization (realm) have changed.
|
|
|
|
[new-user-defaults]: /help/configure-default-new-user-settings
|
|
|
|
See [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)
|
|
for details on possible properties.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 95).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user_settings_defaults
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
The name of the property that was changed.
|
|
value:
|
|
description: |
|
|
The new value of the property.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
example:
|
|
{
|
|
"type": "realm_user_settings_defaults",
|
|
"op": "update",
|
|
"property": "left_side_userlist",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing details of newly created drafts.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
An array containing objects for the newly created drafts.
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "add",
|
|
"drafts":
|
|
[
|
|
{
|
|
"id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"topic": "",
|
|
"content": "Hello there!",
|
|
"timestamp": 15954790200,
|
|
},
|
|
],
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing details for an edited draft.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
draft:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "update",
|
|
"draft":
|
|
{
|
|
"id": 17,
|
|
"type": "private",
|
|
"to": [6, 7, 8, 9, 10],
|
|
"topic": "",
|
|
"content": "Hello everyone!",
|
|
"timestamp": 15954790200,
|
|
},
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing the ID of a deleted draft.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
draft_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft that was just deleted.
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "remove",
|
|
"draft_id": 17,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing details of a newly created saved snippet.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- saved_snippets
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
saved_snippet:
|
|
$ref: "#/components/schemas/SavedSnippet"
|
|
example:
|
|
{
|
|
"type": "saved_snippets",
|
|
"op": "add",
|
|
"saved_snippet":
|
|
{
|
|
"id": 1,
|
|
"title": "Example",
|
|
"content": "Welcome to the organization.",
|
|
"date_created": 1681662420,
|
|
},
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing the ID of a deleted saved snippet.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- saved_snippets
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
saved_snippet_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the saved snippet that was just deleted.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
example:
|
|
{
|
|
"type": "saved_snippets",
|
|
"op": "remove",
|
|
"saved_snippet_id": 17,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when scheduled messages
|
|
are created.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 179).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
scheduled_messages:
|
|
type: array
|
|
description: |
|
|
An array of objects containing details of the newly created
|
|
scheduled messages.
|
|
items:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "add",
|
|
"scheduled_messages":
|
|
[
|
|
{
|
|
"scheduled_message_id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"content": "Hello there!",
|
|
"rendered_content": "<p>Hello there!</p>",
|
|
"scheduled_delivery_timestamp": 1681662420,
|
|
"failed": false,
|
|
},
|
|
],
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when a scheduled message
|
|
is edited.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 179).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
scheduled_message:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "update",
|
|
"scheduled_message":
|
|
{
|
|
"scheduled_message_id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"content": "Hello there!",
|
|
"rendered_content": "<p>Hello there!</p>",
|
|
"scheduled_delivery_timestamp": 1681662420,
|
|
"failed": false,
|
|
},
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when a scheduled message
|
|
is deleted.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 179).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
scheduled_message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the scheduled message that was deleted.
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "remove",
|
|
"scheduled_message_id": 17,
|
|
}
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
The ID of the registered queue.
|
|
example:
|
|
{
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"events":
|
|
[
|
|
{
|
|
"id": 0,
|
|
"message":
|
|
{
|
|
"avatar_url": "https://url/for/othello-bots/avatar",
|
|
"client": "website",
|
|
"content": "I come not, friends, to steal away your hearts.",
|
|
"content_type": "text/x-markdown",
|
|
"display_recipient": "Denmark",
|
|
"id": 12345678,
|
|
"recipient_id": 12314,
|
|
"sender_email": "othello-bot@example.com",
|
|
"sender_full_name": "Othello Bot",
|
|
"sender_id": 13215,
|
|
"sender_realm_str": "example",
|
|
"topic_links": [],
|
|
"timestamp": 1375978403,
|
|
"type": "stream",
|
|
},
|
|
"type": "message",
|
|
},
|
|
{
|
|
"id": 1,
|
|
"message":
|
|
{
|
|
"avatar_url": "https://url/for/othello-bots/avatar",
|
|
"client": "website",
|
|
"content": "With mirth and laughter let old wrinkles come.",
|
|
"content_type": "text/x-markdown",
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"email": "hamlet@example.com",
|
|
"full_name": "Hamlet of Denmark",
|
|
"id": 31572,
|
|
},
|
|
],
|
|
"id": 12345679,
|
|
"recipient_id": 18391,
|
|
"sender_email": "othello-bot@example.com",
|
|
"sender_full_name": "Othello Bot",
|
|
"sender_id": 13215,
|
|
"sender_realm_str": "example",
|
|
"subject": "",
|
|
"topic_links": [],
|
|
"timestamp": 1375978404,
|
|
"type": "private",
|
|
},
|
|
"type": "message",
|
|
},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BadEventQueueIdError"
|
|
- description: |
|
|
#### BAD_EVENT_QUEUE_ID errors
|
|
|
|
This error occurs if the target event queue has been garbage collected.
|
|
A compliant client will handle this error by re-initializing itself
|
|
(e.g. a Zulip web app browser window will reload in this case).
|
|
|
|
See [the /register endpoint docs](/api/register-queue) for details on how to
|
|
handle these correctly.
|
|
|
|
The following is the error response in such case:
|
|
delete:
|
|
operationId: delete-queue
|
|
summary: Delete an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
Delete a previously registered queue.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
queue_id:
|
|
description: |
|
|
The ID of an event queue that was previously registered via
|
|
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
|
|
type: string
|
|
example: fb67bf8a-c031-47cc-84cf-ed80accacda8
|
|
required:
|
|
- queue_id
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BadEventQueueIdError"
|
|
- description: |
|
|
A typical JSON response for when the `queue_id` is non-existent or the
|
|
associated queue has already been deleted:
|
|
/get_stream_id:
|
|
get:
|
|
operationId: get-stream-id
|
|
summary: Get channel ID
|
|
tags: ["channels"]
|
|
description: |
|
|
Get the unique ID of a given channel.
|
|
parameters:
|
|
- name: stream
|
|
in: query
|
|
description: |
|
|
The name of the channel to access.
|
|
schema:
|
|
type: string
|
|
example: Denmark
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the given channel.
|
|
example: {"msg": "", "result": "success", "stream_id": 15}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid channel name 'nonexistent'",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the supplied channel does not exist:
|
|
/mark_all_as_read:
|
|
post:
|
|
deprecated: true
|
|
operationId: mark-all-as-read
|
|
summary: Mark all messages as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Marks all of the current user's unread messages as read.
|
|
|
|
Because this endpoint marks messages as read in batches, it is possible
|
|
for the request to time out after only marking some messages as read.
|
|
When this happens, the `complete` boolean field in the success response
|
|
will be `false`. Clients should repeat the request when handling such a
|
|
response. If all messages were marked as read, then the success response
|
|
will return `"complete": true`.
|
|
|
|
**Changes**: Deprecated; clients should use the [update personal message
|
|
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
|
|
as this endpoint will be removed in a future release.
|
|
|
|
Before Zulip 8.0 (feature level 211), if the server's
|
|
processing was interrupted by a timeout, but some messages were marked
|
|
as read, then it would return `"result": "partially_completed"`, along
|
|
with a `code` field for an error string, in the success response to
|
|
indicate that there was a timeout and that the client should repeat the
|
|
request.
|
|
|
|
Before Zulip 6.0 (feature level 153), this request did a single atomic
|
|
operation, which could time out with 10,000s of unread messages to mark
|
|
as read. As of this feature level, messages are marked as read in
|
|
batches, starting with the newest messages, so that progress is made
|
|
even if the request times out. And, instead of returning an error when
|
|
the request times out and some messages have been marked as read, a
|
|
success response with `"result": "partially_completed"` is returned.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- complete
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
complete:
|
|
type: boolean
|
|
description: |
|
|
Whether all unread messages were marked as read.
|
|
|
|
Will be `false` if the request successfully marked
|
|
some, but not all, messages as read.
|
|
example: {"msg": "", "result": "success", "complete": true}
|
|
/mark_stream_as_read:
|
|
post:
|
|
deprecated: true
|
|
operationId: mark-stream-as-read
|
|
summary: Mark messages in a channel as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Mark all the unread messages in a channel as read.
|
|
|
|
**Changes**: Deprecated; clients should use the [update personal message
|
|
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
|
|
as this endpoint will be removed in a future release.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the channel to access.
|
|
type: integer
|
|
example: 43
|
|
required:
|
|
- stream_id
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/mark_topic_as_read:
|
|
post:
|
|
deprecated: true
|
|
operationId: mark-topic-as-read
|
|
summary: Mark messages in a topic as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Mark all the unread messages in a topic as read.
|
|
|
|
**Changes**: Deprecated; clients should use the [update personal message
|
|
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
|
|
as this endpoint will be removed in a future release.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the channel to access.
|
|
type: integer
|
|
example: 43
|
|
topic_name:
|
|
description: |
|
|
The name of the topic whose messages should be marked as read.
|
|
type: string
|
|
example: new coffee machine
|
|
required:
|
|
- stream_id
|
|
- topic_name
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/attachments:
|
|
get:
|
|
operationId: get-attachments
|
|
summary: Get attachments
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch metadata on files uploaded by the requesting user.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
attachments:
|
|
type: array
|
|
description: |
|
|
A list of `attachment` objects, each containing
|
|
details about a file uploaded by the user.
|
|
items:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by users in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"attachments":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "166050.jpg",
|
|
"path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
|
|
"size": 571946,
|
|
"create_time": 1588145417000,
|
|
"messages":
|
|
[
|
|
{"id": 102, "date_sent": 1588145424000},
|
|
{"id": 103, "date_sent": 1588145448000},
|
|
],
|
|
},
|
|
],
|
|
"upload_space_used": 571946,
|
|
}
|
|
/attachments/{attachment_id}:
|
|
delete:
|
|
operationId: remove-attachment
|
|
summary: Delete an attachment
|
|
tags: ["users"]
|
|
description: |
|
|
Delete an uploaded file given its attachment ID.
|
|
|
|
Note that uploaded files that have been referenced in at least
|
|
one message are automatically deleted once the last message
|
|
containing a link to them is deleted (whether directly or via
|
|
a [message retention policy](/help/message-retention-policy)).
|
|
|
|
Uploaded files that are never used in a message are
|
|
automatically deleted a few weeks after being uploaded.
|
|
|
|
Attachment IDs can be contained from [GET /attachments](/api/get-attachments).
|
|
parameters:
|
|
- name: attachment_id
|
|
in: path
|
|
description: |
|
|
The ID of the attachment to be deleted.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid attachment",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the `attachment_id` is invalid
|
|
"401":
|
|
description: Error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "UNAUTHORIZED",
|
|
"result": "error",
|
|
"msg": "Not logged in: API authentication or user session required",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the user is not logged in:
|
|
/drafts:
|
|
get:
|
|
operationId: get-drafts
|
|
tags: ["drafts"]
|
|
summary: Get drafts
|
|
description: |
|
|
Fetch all drafts for the current user.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
count:
|
|
type: integer
|
|
description: |
|
|
The number of drafts the user currently has. Also the
|
|
number of drafts returned under "drafts".
|
|
example: 3
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
Returns all of the current user's drafts, in order of last edit time
|
|
(with the most recently edited draft appearing first).
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"count": 3,
|
|
"drafts":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"type": "stream",
|
|
"to": [3],
|
|
"topic": "sync drafts",
|
|
"content": "Let's add backend support for syncing drafts.",
|
|
"timestamp": 1595479019,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"type": "private",
|
|
"to": [4],
|
|
"topic": "",
|
|
"content": "What if we made it possible to sync drafts in Zulip?",
|
|
"timestamp": 1595479019,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"type": "private",
|
|
"to": [4, 10],
|
|
"topic": "",
|
|
"content": "What if we made it possible to sync drafts in Zulip?",
|
|
"timestamp": 1595479019,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-drafts
|
|
tags: ["drafts"]
|
|
summary: Create drafts
|
|
description: |
|
|
Create one or more drafts on the server. These drafts will be automatically
|
|
synchronized to other clients via `drafts` events.
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
drafts:
|
|
description: |
|
|
A JSON-encoded list of containing new draft objects.
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
[
|
|
{
|
|
"type": "stream",
|
|
"to": [1],
|
|
"topic": "questions",
|
|
"content": "What are the contribution guidelines for this project?",
|
|
"timestamp": 1595479019,
|
|
},
|
|
]
|
|
encoding:
|
|
drafts:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
ids:
|
|
type: array
|
|
description: |
|
|
An array of the IDs for the drafts that were just created in the same
|
|
order as they were submitted.
|
|
items:
|
|
type: integer
|
|
example: {"result": "success", "msg": "", "ids": [1, 2, 3]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
JSON response for when a draft targeted towards a channel does not specify
|
|
exactly one channel ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Must specify exactly 1 channel ID for channel messages",
|
|
"result": "error",
|
|
}
|
|
/drafts/{draft_id}:
|
|
patch:
|
|
operationId: edit-draft
|
|
tags: ["drafts"]
|
|
summary: Edit a draft
|
|
description: |
|
|
Edit a draft on the server. The edit will be automatically
|
|
synchronized to other clients via `drafts` events.
|
|
parameters:
|
|
- name: draft_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft to be edited.
|
|
required: true
|
|
example: 2
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
draft:
|
|
allOf:
|
|
- $ref: "#/components/schemas/Draft"
|
|
- description: |
|
|
A JSON-encoded object containing a replacement draft object for this ID.
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"to": [1],
|
|
"topic": "questions",
|
|
"content": "how tough is a Lamy Safari?",
|
|
"timestamp": 1595479019,
|
|
}
|
|
required:
|
|
- draft
|
|
encoding:
|
|
draft:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when no draft exists with
|
|
the provided ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Draft does not exist",
|
|
}
|
|
delete:
|
|
operationId: delete-draft
|
|
tags: ["drafts"]
|
|
summary: Delete a draft
|
|
description: |
|
|
Delete a single draft from the server. The deletion will be automatically
|
|
synchronized to other clients via a `drafts` event.
|
|
parameters:
|
|
- name: draft_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft you want to delete.
|
|
required: true
|
|
example: 1
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when no draft exists with
|
|
the provided ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Draft does not exist",
|
|
}
|
|
/saved_snippets:
|
|
get:
|
|
operationId: get-saved-snippets
|
|
tags: ["drafts"]
|
|
summary: Get all saved snippets
|
|
description: |
|
|
Fetch all the saved snippets for the current user.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
saved_snippets:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries containing data on all of the current user's
|
|
saved snippets.
|
|
items:
|
|
$ref: "#/components/schemas/SavedSnippet"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"saved_snippets":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"title": "Example",
|
|
"content": "Welcome to the organization.",
|
|
"date_created": 1681662420,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-saved-snippet
|
|
tags: ["drafts"]
|
|
summary: Create a saved snippet
|
|
description: |
|
|
Create a new saved snippet for the current user.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: |
|
|
The title of the saved snippet.
|
|
example: Example title
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content of the saved snippet in text/markdown format.
|
|
|
|
Clients should insert this content into a message when using
|
|
a saved snippet.
|
|
example: Welcome to the organization.
|
|
required:
|
|
- title
|
|
- content
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
saved_snippet_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the saved snippet created.
|
|
example:
|
|
{"result": "success", "msg": "", "saved_snippet_id": 1}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Title cannot be empty.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when either title or content is
|
|
empty:
|
|
/saved_snippets/{saved_snippet_id}:
|
|
delete:
|
|
operationId: delete-saved-snippet
|
|
tags: ["drafts"]
|
|
summary: Delete a saved snippet
|
|
description: |
|
|
Delete a saved snippet.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
parameters:
|
|
- name: saved_snippet_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the saved snippet to delete.
|
|
required: true
|
|
example: 2
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when no saved snippet exists
|
|
with the provided ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Saved snippet does not exist.",
|
|
}
|
|
/scheduled_messages:
|
|
get:
|
|
operationId: get-scheduled-messages
|
|
tags: ["scheduled_messages"]
|
|
summary: Get scheduled messages
|
|
description: |
|
|
Fetch all [scheduled messages](/help/schedule-a-message) for
|
|
the current user.
|
|
|
|
Scheduled messages are messages the user has scheduled to be
|
|
sent in the future via the send later feature.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 173).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
scheduled_messages:
|
|
type: array
|
|
description: |
|
|
Returns all of the current user's undelivered scheduled
|
|
messages, ordered by `scheduled_delivery_timestamp`
|
|
(ascending).
|
|
items:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"scheduled_messages":
|
|
[
|
|
{
|
|
"scheduled_message_id": 27,
|
|
"to": 14,
|
|
"type": "stream",
|
|
"content": "Hi",
|
|
"rendered_content": "<p>Hi</p>",
|
|
"topic": "Introduction",
|
|
"scheduled_delivery_timestamp": 1681662420,
|
|
"failed": false,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-scheduled-message
|
|
tags: ["scheduled_messages"]
|
|
summary: Create a scheduled message
|
|
description: |
|
|
Create a new [scheduled message](/help/schedule-a-message).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 184), moved support for
|
|
[editing a scheduled message](/api/update-scheduled-message) to a
|
|
separate API endpoint, which removed the `scheduled_message_id`
|
|
parameter from this endpoint.
|
|
|
|
New in Zulip 7.0 (feature level 179).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
description: |
|
|
The type of scheduled message to be sent. `"direct"` for a direct
|
|
message and `"stream"` or `"channel"` for a channel message.
|
|
|
|
Note that, while `"private"` is supported for scheduling direct
|
|
messages, clients are encouraged to use to the modern convention of
|
|
`"direct"` to indicate this message type, because support for
|
|
`"private"` may eventually be removed.
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
|
|
an additional value for this parameter to indicate the type of a channel
|
|
message.
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- channel
|
|
- stream
|
|
- private
|
|
example: direct
|
|
to:
|
|
description: |
|
|
The scheduled message's tentative target audience.
|
|
|
|
For channel messages, the integer ID of the channel.
|
|
For direct messages, a list containing integer user IDs.
|
|
oneOf:
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: [9, 10]
|
|
content:
|
|
$ref: "#/components/schemas/RequiredContent"
|
|
topic:
|
|
description: |
|
|
The topic of the message. Only required for channel messages
|
|
(`"type": "stream"` or `"type": "channel"`), ignored otherwise.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
type: string
|
|
example: Castle
|
|
scheduled_delivery_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message will be sent,
|
|
in UTC seconds.
|
|
example: 3165826990
|
|
read_by_sender:
|
|
type: boolean
|
|
description: |
|
|
Whether the message should be initially marked read by its
|
|
sender. If unspecified, the server uses a heuristic based
|
|
on the client name and the recipient.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 236).
|
|
example: true
|
|
required:
|
|
- type
|
|
- to
|
|
- content
|
|
- scheduled_delivery_timestamp
|
|
encoding:
|
|
to:
|
|
contentType: application/json
|
|
scheduled_delivery_timestamp:
|
|
contentType: application/json
|
|
read_by_sender:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
scheduled_message_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the scheduled message.
|
|
|
|
This is different from the unique ID that the message will have
|
|
after it is sent.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"scheduled_message_id": 42,
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/NonExistingChannelIdError"
|
|
- description: |
|
|
A typical failed JSON response for when a channel message is scheduled
|
|
to be sent to a channel that does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user ID 10",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a direct message is scheduled
|
|
to be sent to a user that does not exist:
|
|
/scheduled_messages/{scheduled_message_id}:
|
|
patch:
|
|
operationId: update-scheduled-message
|
|
tags: ["scheduled_messages"]
|
|
summary: Edit a scheduled message
|
|
description: |
|
|
Edit an existing [scheduled message](/help/schedule-a-message).
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 184).
|
|
parameters:
|
|
- name: scheduled_message_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the scheduled message to update.
|
|
|
|
This is different from the unique ID that the message would have
|
|
after being sent.
|
|
required: true
|
|
example: 2
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
description: |
|
|
The type of scheduled message to be sent. `"direct"` for a direct
|
|
message and `"stream"` or `"channel"` for a channel message.
|
|
|
|
When updating the type of the scheduled message, the `to` parameter
|
|
is required. And, if updating the type of the scheduled message to
|
|
`"stream"`/`"channel"`, then the `topic` parameter is also required.
|
|
|
|
Note that, while `"private"` is supported for scheduling direct
|
|
messages, clients are encouraged to use to the modern convention of
|
|
`"direct"` to indicate this message type, because support for
|
|
`"private"` may eventually be removed.
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
|
|
an additional value for this parameter to indicate the type of a channel
|
|
message.
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- channel
|
|
- stream
|
|
- private
|
|
example: stream
|
|
to:
|
|
description: |
|
|
The scheduled message's tentative target audience.
|
|
|
|
For channel messages, the integer ID of the channel.
|
|
For direct messages, a list containing integer user IDs.
|
|
|
|
Required when updating the `type` of the scheduled message.
|
|
oneOf:
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: 11
|
|
content:
|
|
description: |
|
|
The updated content of the scheduled message.
|
|
|
|
Clients should use the `max_message_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum message size.
|
|
type: string
|
|
example: Hello
|
|
topic:
|
|
description: |
|
|
The updated topic of the scheduled message.
|
|
|
|
Required when updating the `type` of the scheduled message to
|
|
`"stream"` or `"channel"`. Ignored when the existing or updated
|
|
`type` of the scheduled message is `"direct"` (or `"private"`).
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
type: string
|
|
example: Castle
|
|
scheduled_delivery_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message will be sent,
|
|
in UTC seconds.
|
|
|
|
Required when updating a scheduled message that the server
|
|
has already tried and failed to send. This state is indicated
|
|
with `"failed": true` in `scheduled_messages` objects; see
|
|
response description at
|
|
[`GET /scheduled_messages`](/api/get-scheduled-messages#response).
|
|
example: 3165826990
|
|
encoding:
|
|
to:
|
|
contentType: application/json
|
|
scheduled_delivery_timestamp:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
example: {"result": "success", "msg": ""}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/NonExistingChannelIdError"
|
|
- description: |
|
|
A typical failed JSON response for when a channel message is scheduled
|
|
to be sent to a channel that does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user ID 10",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a direct message is scheduled
|
|
to be sent to a user that does not exist:
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when no scheduled message exists
|
|
with the provided ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Scheduled message does not exist",
|
|
}
|
|
delete:
|
|
operationId: delete-scheduled-message
|
|
tags: ["scheduled_messages"]
|
|
summary: Delete a scheduled message
|
|
description: |
|
|
Delete, and therefore cancel sending, a previously [scheduled
|
|
message](/help/schedule-a-message).
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 173).
|
|
parameters:
|
|
- name: scheduled_message_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the scheduled message to delete.
|
|
|
|
This is different from the unique ID that the message would have
|
|
after being sent.
|
|
required: true
|
|
example: 1
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when no scheduled message exists
|
|
with the provided ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Scheduled message does not exist",
|
|
}
|
|
/default_streams:
|
|
post:
|
|
operationId: add-default-stream
|
|
tags: ["channels"]
|
|
summary: Add a default channel
|
|
x-requires-administrator: true
|
|
description: |
|
|
Add a channel to the set of [default channels][default-channels]
|
|
for new users joining the organization.
|
|
|
|
[default-channels]: /help/set-default-channels-for-new-users
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the target channel.
|
|
type: integer
|
|
example: 10
|
|
required:
|
|
- stream_id
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
A typical failed JSON response for when an invalid channel ID is passed:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Private channels cannot be made default.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a user tries to add a private channel
|
|
to the default channels set:
|
|
delete:
|
|
operationId: remove-default-stream
|
|
summary: Remove a default channel
|
|
tags: ["channels"]
|
|
description: |
|
|
Remove a channel from the set of [default channels][default-channels]
|
|
for new users joining the organization.
|
|
|
|
[default-channels]: /help/set-default-channels-for-new-users
|
|
x-requires-administrator: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the target channel.
|
|
type: integer
|
|
example: 10
|
|
required:
|
|
- stream_id
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
A typical failed JSON response for when an invalid channel ID is passed:
|
|
/messages:
|
|
get:
|
|
operationId: get-messages
|
|
summary: Get messages
|
|
tags: ["messages"]
|
|
description: |
|
|
This endpoint is the primary way to fetch a messages. It is used by all official
|
|
Zulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as
|
|
many bots, API clients, backup scripts, etc.
|
|
|
|
Most queries will specify a [narrow filter](/api/get-messages#parameter-narrow),
|
|
to fetch the messages matching any supported [search
|
|
query](/help/search-for-messages). If not specified, it will return messages
|
|
corresponding to the user's [combined feed](/help/combined-feed). There are two
|
|
ways to specify which messages matching the narrow filter to fetch:
|
|
|
|
- A range of messages, described by an `anchor` message ID (or a string-format
|
|
specification of how the server should computer an anchor to use) and a maximum
|
|
number of messages in each direction from that anchor.
|
|
|
|
- A rarely used variant (`message_ids`) where the client specifies the message IDs
|
|
to fetch.
|
|
|
|
The server returns the matching messages, sorted by message ID, as well as some
|
|
metadata that makes it easy for a client to determine whether there are more
|
|
messages matching the query that were not returned due to the `num_before` and
|
|
`num_after` limits.
|
|
|
|
Note that a user's message history does not contain messages sent to
|
|
channels before they [subscribe](/api/subscribe), and newly created
|
|
bot users are not usually subscribed to any channels.
|
|
|
|
We recommend requesting at most 1000 messages in a batch, to avoid generating very
|
|
large HTTP responses. A maximum of 5000 messages can be obtained per request;
|
|
attempting to exceed this will result in an error.
|
|
|
|
**Changes**: The `message_ids` option is new in Zulip 10.0 (feature level 300).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- client_gravatar
|
|
- apply_markdown
|
|
- use_first_unread_anchor
|
|
- include_anchor
|
|
- message_ids
|
|
parameters:
|
|
- name: anchor
|
|
in: query
|
|
description: |
|
|
Integer message ID to anchor fetching of new messages. Supports special
|
|
string values for when the client wants the server to compute the anchor
|
|
to use:
|
|
|
|
- `newest`: The most recent message.
|
|
- `oldest`: The oldest message.
|
|
- `first_unread`: The oldest unread message matching the
|
|
query, if any; otherwise, the most recent message.
|
|
|
|
**Changes**: String values are new in Zulip 3.0 (feature level 1). The
|
|
`first_unread` functionality was supported in Zulip 2.1.x
|
|
and older by not sending `anchor` and using `use_first_unread_anchor`.
|
|
|
|
In Zulip 2.1.x and older, `oldest` can be emulated with
|
|
`"anchor": 0`, and `newest` with `"anchor": 10000000000000000`
|
|
(that specific large value works around a bug in Zulip
|
|
2.1.x and older in the `found_newest` return value).
|
|
schema:
|
|
$ref: "#/components/schemas/Anchor"
|
|
example: "43"
|
|
- name: include_anchor
|
|
in: query
|
|
description: |
|
|
Whether a message with the specified ID matching the narrow
|
|
should be included.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 155).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: num_before
|
|
in: query
|
|
description: |
|
|
The number of messages with IDs less than the anchor to retrieve.
|
|
Required if `message_ids` is not provided.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 4
|
|
required: false
|
|
- name: num_after
|
|
in: query
|
|
description: |
|
|
The number of messages with IDs greater than the anchor to retrieve.
|
|
Required if `message_ids` is not provided.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 8
|
|
required: false
|
|
- name: narrow
|
|
in: query
|
|
description: |
|
|
The narrow where you want to fetch the messages from. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
Note that many narrows, including all that lack a `channel`, `channels`,
|
|
`stream`, or `streams` operator, search the user's personal message
|
|
history. See [searching shared
|
|
history](/help/search-for-messages#searching-shared-history)
|
|
for details.
|
|
|
|
For example, if you would like to fetch messages from all public channels instead
|
|
of only the user's message history, then a specific narrow for
|
|
messages sent to all public channels can be used:
|
|
`{"operator": "channels", "operand": "public"}`.
|
|
|
|
Newly created bot users are not usually subscribed to any
|
|
channels, so bots using this API should either be
|
|
subscribed to appropriate channels or use a shared history
|
|
search narrow with this endpoint.
|
|
|
|
**Changes**: See [changes section](/api/construct-narrow#changes)
|
|
of search/narrow filter documentation.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
required:
|
|
- operator
|
|
- operand
|
|
additionalProperties: false
|
|
properties:
|
|
operator:
|
|
type: string
|
|
operand:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
negated:
|
|
type: boolean
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minItems: 2
|
|
maxItems: 2
|
|
default: []
|
|
example: [{"operand": "Denmark", "operator": "channel"}]
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- name: apply_markdown
|
|
in: query
|
|
description: |
|
|
If `true`, message content is returned in the rendered HTML
|
|
format. If `false`, message content is returned in the raw
|
|
Markdown-format text that user entered.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: use_first_unread_anchor
|
|
in: query
|
|
deprecated: true
|
|
description: |
|
|
Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older.
|
|
|
|
Whether to use the (computed by the server) first unread message
|
|
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by
|
|
`"anchor": "first_unread"`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: message_ids
|
|
in: query
|
|
description: |
|
|
A list of message IDs to fetch. The server will return messages corresponding to the
|
|
subset of the requested message IDs that exist and the current user has access to,
|
|
potentially filtered by the narrow (if that parameter is provided).
|
|
|
|
It is an error to pass this parameter as well as any of the parameters involved in
|
|
specifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`,
|
|
`num_before`, and `num_after`.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 300). Previously, there was
|
|
no way to request a specific set of messages IDs.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 2, 3]
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- result
|
|
- msg
|
|
- messages
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
anchor:
|
|
type: integer
|
|
description: |
|
|
The same `anchor` specified in the request (or the computed one, if
|
|
`use_first_unread_anchor` is `true`).
|
|
|
|
Only present if `message_ids` is not provided.
|
|
found_newest:
|
|
type: boolean
|
|
description: |
|
|
Whether the server promises that the `messages` list includes the very
|
|
newest messages matching the narrow (used by clients that paginate their
|
|
requests to decide whether there may be more messages to fetch).
|
|
found_oldest:
|
|
type: boolean
|
|
description: |
|
|
Whether the server promises that the `messages` list includes the very
|
|
oldest messages matching the narrow (used by clients that paginate their
|
|
requests to decide whether there may be more messages to fetch).
|
|
found_anchor:
|
|
type: boolean
|
|
description: |
|
|
Whether the anchor message is included in the
|
|
response. If the message with the ID specified
|
|
in the request does not exist, did not match
|
|
the narrow, or was excluded via
|
|
`"include_anchor": false`, this will be false.
|
|
history_limited:
|
|
type: boolean
|
|
description: |
|
|
Whether the message history was limited due to
|
|
plan restrictions. This flag is set to `true`
|
|
only when the oldest messages(`found_oldest`)
|
|
matching the narrow is fetched.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
An array of `message` objects.
|
|
|
|
**Changes**: In Zulip 3.1 (feature level 26), the
|
|
`sender_short_name` field was removed from message
|
|
objects.
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
|
|
flag was deprecated in favor of the `stream_wildcard_mentioned` and
|
|
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
|
|
for backwards compatibility with older clients and equals
|
|
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
|
|
supporting older server versions should treat this field as a previous
|
|
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
|
|
were not available prior to this feature level.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
match_content:
|
|
type: string
|
|
description: |
|
|
Only present if keyword search was included among the narrow parameters.
|
|
|
|
HTML content of a queried message that matches the narrow, with
|
|
`<span class="highlight">` elements wrapping the matches for the
|
|
search keywords.
|
|
match_subject:
|
|
type: string
|
|
description: |
|
|
Only present if keyword search was included among the narrow parameters.
|
|
|
|
HTML-escaped topic of a queried message that matches the narrow, with
|
|
`<span class="highlight">` elements wrapping the matches for the
|
|
search keywords.
|
|
example:
|
|
{
|
|
"anchor": 21,
|
|
"found_newest": true,
|
|
"found_anchor": true,
|
|
"result": "success",
|
|
"msg": "",
|
|
"messages":
|
|
[
|
|
{
|
|
"subject": "",
|
|
"sender_realm_str": "zulip",
|
|
"type": "private",
|
|
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
|
|
"flags": ["read"],
|
|
"id": 16,
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"id": 4,
|
|
"is_mirror_dummy": false,
|
|
"email": "hamlet@zulip.com",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
{
|
|
"id": 5,
|
|
"is_mirror_dummy": false,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago",
|
|
},
|
|
{
|
|
"id": 8,
|
|
"is_mirror_dummy": false,
|
|
"email": "prospero@zulip.com",
|
|
"full_name": "Prospero from The Tempest",
|
|
},
|
|
],
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527921326,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 27,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
{
|
|
"subject": "Verona3",
|
|
"stream_id": 5,
|
|
"sender_realm_str": "zulip",
|
|
"type": "stream",
|
|
"content": "<p>Wait, is this from the frontend js code or backend python code</p>",
|
|
"flags": ["read"],
|
|
"id": 21,
|
|
"display_recipient": "Verona",
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527939746,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 20,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: send-message
|
|
summary: Send a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Send a [channel message](/help/introduction-to-topics) or a
|
|
[direct message](/help/direct-messages).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
description: |
|
|
The type of message to be sent.
|
|
|
|
`"direct"` for a direct message and `"stream"` or `"channel"` for a
|
|
channel message.
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
|
|
an additional value for this parameter to request a channel message.
|
|
|
|
In Zulip 7.0 (feature level 174), `"direct"` was added as
|
|
the preferred way to request a direct message, deprecating the original
|
|
`"private"`. While `"private"` is still supported for requesting direct
|
|
messages, clients are encouraged to use to the modern convention with
|
|
servers that support it, because support for `"private"` will eventually
|
|
be removed.
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- channel
|
|
- stream
|
|
- private
|
|
example: direct
|
|
to:
|
|
description: |
|
|
For channel messages, either the name or integer ID of the channel. For
|
|
direct messages, either a list containing integer user IDs or a list
|
|
containing string Zulip API email addresses.
|
|
|
|
**Changes**: Support for using user/channel IDs was added in Zulip 2.0.0.
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: string
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: [9, 10]
|
|
content:
|
|
$ref: "#/components/schemas/RequiredContent"
|
|
topic:
|
|
description: |
|
|
The topic of the message. Only required for channel messages
|
|
(`"type": "stream"` or `"type": "channel"`), ignored otherwise.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
|
|
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
|
|
this as `subject`, which is currently a deprecated alias.
|
|
type: string
|
|
example: Castle
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
For clients supporting
|
|
[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),
|
|
the [event queue](/api/register-queue)
|
|
ID for the client. If passed, `local_id` is required. If the message is
|
|
successfully sent, the server will include `local_id` in the `message` event
|
|
that the client with this `queue_id` will receive notifying it of the new message
|
|
via [`GET /events`](/api/get-events). This lets the client know unambiguously
|
|
that it should replace the locally echoed message, rather than adding this new
|
|
message (which would be correct if the user had sent the new message from another
|
|
device).
|
|
example: "fb67bf8a-c031-47cc-84cf-ed80accacda8"
|
|
local_id:
|
|
type: string
|
|
description: |
|
|
For clients supporting local echo, a unique string-format identifier
|
|
chosen freely by the client; the server will pass it back to the client without
|
|
inspecting it, as described in the `queue_id` description.
|
|
example: "100.01"
|
|
read_by_sender:
|
|
type: boolean
|
|
description: |
|
|
Whether the message should be initially marked read by its
|
|
sender. If unspecified, the server uses a heuristic based
|
|
on the client name.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 236).
|
|
example: true
|
|
required:
|
|
- type
|
|
- to
|
|
- content
|
|
encoding:
|
|
to:
|
|
contentType: application/json
|
|
read_by_sender:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- id
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID assigned to the sent message.
|
|
automatic_new_visibility_policy:
|
|
type: integer
|
|
enum:
|
|
- 2
|
|
- 3
|
|
description: |
|
|
If the message's sender had configured their [visibility policy settings](/help/mute-a-topic)
|
|
to potentially automatically follow or unmute topics when sending messages,
|
|
and one of these policies did in fact change the user's visibility policy
|
|
for the topic where this message was sent, the new value for that user's
|
|
visibility policy for the recipient topic.
|
|
|
|
Only present if the sender's visibility was in fact changed.
|
|
|
|
The value can be either [unmuted or followed](/api/update-user-topic#parameter-visibility_policy).
|
|
|
|
Clients will also be notified about the change in policy via a
|
|
`user_topic` event as usual. This field is intended to be used by clients
|
|
to explicitly inform the user when a topic's visibility policy was changed
|
|
automatically due to sending a message.
|
|
|
|
For example, the Zulip web application uses this field to decide whether
|
|
to display a warning or notice suggesting to unmute the topic after
|
|
sending a message to a muted channel. Such a notice would be confusing in
|
|
the event that the act of sending the message had already resulted in the
|
|
user automatically unmuting or following the topic in question.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 218).
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"id": 42,
|
|
"automatic_new_visibility_policy": 2,
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/NonExistingChannelNameError"
|
|
- description: |
|
|
A typical failed JSON response for when a channel message is sent to a channel
|
|
that does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid email 'eeshan@zulip.com'",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a direct message is sent to a user
|
|
that does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "You do not have permission to use channel wildcard mentions in this channel.",
|
|
"code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the message was rejected because
|
|
of the organization's `wildcard_mention_policy` and large number of
|
|
subscribers to the channel.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 229). Previously, this
|
|
error returned the `"BAD_REQUEST"` code.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "You do not have permission to use topic wildcard mentions in this topic.",
|
|
"code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the message was rejected because
|
|
the message contains a topic wildcard mention, but the user doesn't have
|
|
permission to use such a mention in this topic due to the
|
|
`wildcard_mention_policy` (and large number of participants in this
|
|
specific topic).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 229). Previously,
|
|
`wildcard_mention_policy` was not enforced for topic mentions.
|
|
/messages/{message_id}/history:
|
|
get:
|
|
operationId: get-message-history
|
|
summary: Get a message's edit history
|
|
tags: ["messages"]
|
|
description: |
|
|
Fetch the message edit history of a previously edited message.
|
|
|
|
Note that edit history may be disabled in some organizations; see the
|
|
[Zulip Help Center documentation on editing messages][edit-settings].
|
|
|
|
[edit-settings]: /help/view-a-messages-edit-history
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
x-response-description: |
|
|
Please note that the original message's snapshot only contains the fields
|
|
`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This
|
|
snapshot will be the only one present if the message has never been edited.
|
|
|
|
Also note that each snapshot object will only contain additional data for the
|
|
modified fields for that particular edit (e.g. if only the topic or channel
|
|
was edited, `prev_content`, `prev_rendered_content`, and
|
|
`content_html_diff` will not appear).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
message_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
topic:
|
|
type: string
|
|
description: |
|
|
The topic of the message immediately
|
|
after this edit event.
|
|
prev_topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately
|
|
prior to this edit event.
|
|
stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's channel was edited.
|
|
|
|
The ID of the channel containing the message
|
|
immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
prev_stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's channel was edited.
|
|
|
|
The ID of the channel containing the message immediately
|
|
prior to this edit event.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
content:
|
|
type: string
|
|
description: |
|
|
The raw Markdown content of the message
|
|
immediately after this edit event.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The rendered HTML representation of `content`.
|
|
prev_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The raw Markdown content of the message immediately
|
|
prior to this edit event.
|
|
prev_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The rendered HTML representation of `prev_content`.
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user that made the edit.
|
|
|
|
Will be `null` only for edit history
|
|
events predating March 2017.
|
|
|
|
Clients can display edit history events where this
|
|
is `null` as modified by either the sender (for content
|
|
edits) or an unknown user (for topic edits).
|
|
content_html_diff:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
An HTML diff between this version of the message
|
|
and the previous one.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for this edit.
|
|
description: |
|
|
A chronologically sorted, oldest to newest, array
|
|
of `snapshot` objects, each one with the values of
|
|
the message after the edit.
|
|
example:
|
|
{
|
|
"message_history":
|
|
[
|
|
{
|
|
"content": "Hello!",
|
|
"topic": "party at my houz",
|
|
"rendered_content": "<p>Hello!</p>",
|
|
"timestamp": 1530129122,
|
|
"user_id": 5,
|
|
},
|
|
{
|
|
"topic": "party at my house",
|
|
"content": "Howdy!",
|
|
"prev_content": "Hello!",
|
|
"rendered_content": "<p>Howdy!</p>",
|
|
"user_id": 5,
|
|
"prev_rendered_content": "<p>Hello!</p>",
|
|
"content_html_diff": '<div><p><span class="highlight_text_inserted">Howdy!</span></p> <p><span class="highlight_text_deleted">Hello!</span></p></div>',
|
|
"prev_topic": "party at my houz",
|
|
"timestamp": 1530129134,
|
|
},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist:
|
|
/messages/flags:
|
|
post:
|
|
operationId: update-message-flags
|
|
summary: Update personal message flags
|
|
tags: ["messages"]
|
|
description: |
|
|
Add or remove personal message flags like `read` and `starred`
|
|
on a collection of message IDs.
|
|
|
|
See also the endpoint for [updating flags on a range of
|
|
messages within a narrow](/api/update-message-flags-for-narrow).
|
|
x-parameter-description: |
|
|
## Available flags
|
|
<div>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th style="width:30%">Flag</th>
|
|
<th style="width:70%">Purpose</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>read</code></td>
|
|
<td>
|
|
Whether the user has read the message. Messages
|
|
start out unread (except for messages the user
|
|
themself sent using a non-API client) and can
|
|
later be marked as read.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>starred</code></td>
|
|
<td>Whether the user has <a href="/help/star-a-message">starred this message</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>collapsed</code></td>
|
|
<td>Whether the user has <a href="/help/collapse-a-message">collapsed this message</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>mentioned</code></td>
|
|
<td>
|
|
Whether the current user
|
|
<a href="/help/mention-a-user-or-group">was mentioned</a>
|
|
by this message, either directly or via a user
|
|
group. Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
a mention of the current user.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>stream_wildcard_mentioned</code></td>
|
|
<td>
|
|
Whether this message contained a
|
|
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-channel">channel wildcard mention</a>
|
|
(like @**all**). Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
a channel wildcard mention.
|
|
<br /><br />
|
|
<b>Changes</b>: New in Zulip 8.0 (feature level 224).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>topic_wildcard_mentioned</code></td>
|
|
<td>
|
|
Whether this message contained a
|
|
<a href="/help/mention-a-user-or-group#mention-all-topic-participants">topic wildcard mention</a>
|
|
(@**topic**).
|
|
Cannot be changed by the user directly, but can change if
|
|
the message is edited to add/remove a topic wildcard mention.
|
|
<br /><br />
|
|
<b>Changes</b>: New in Zulip 8.0 (feature level 224).
|
|
</td>
|
|
<tr>
|
|
<td><code>has_alert_word</code></td>
|
|
<td>
|
|
Whether the message contains any of the current user's
|
|
<a href="/help/dm-mention-alert-notifications#alert-words">configured alert words</a>.
|
|
Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
one of the current user's alert words.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>historical</code></td>
|
|
<td>
|
|
Is <code>true</code> for messages that the user did not receive
|
|
at the time they were sent but later was added to
|
|
the user's history (e.g. because they starred or
|
|
reacted to a message sent to a public channel
|
|
before they subscribed to that channel). Cannot be
|
|
changed by the user directly.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>wildcard_mentioned</code></td>
|
|
<td>
|
|
Whether this message contained either a
|
|
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-channel">channel wildcard mention</a>
|
|
(like @**all**) or a
|
|
<a href="/help/mention-a-user-or-group#mention-all-topic-participants">topic wildcard mention</a>
|
|
(@**topic**). Cannot be changed by the user directly, but can change if
|
|
the message is edited to add/remove a channel and/or topic wildcard
|
|
mention.
|
|
<br /><br />
|
|
<b>Changes</b>: Deprecated in Zulip 8.0 (feature level 224), in favor of
|
|
the <code>stream_wildcard_mentioned</code> and
|
|
<code>topic_wildcard_mentioned</code> flags. The
|
|
<code>wildcard_mentioned</code> flag exists for backwards compatibility
|
|
with older clients and equals
|
|
<code>stream_wildcard_mentioned || topic_wildcard_mentioned</code>.
|
|
Clients supporting older server versions should treat this field as a
|
|
previous name for the <code>stream_wildcard_mentioned</code> flag as
|
|
topic wildcard mentions were not available prior to this feature level.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
messages:
|
|
description: |
|
|
An array containing the IDs of the target messages.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [4, 8, 15]
|
|
op:
|
|
description: |
|
|
Whether to `add` the flag or `remove` it.
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
flag:
|
|
description: |
|
|
The flag that should be added/removed.
|
|
type: string
|
|
example: read
|
|
required:
|
|
- messages
|
|
- op
|
|
- flag
|
|
encoding:
|
|
messages:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
messages:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
An array with the IDs of the modified messages.
|
|
example:
|
|
{"msg": "", "messages": [4, 18, 15], "result": "success"}
|
|
/messages/flags/narrow:
|
|
post:
|
|
operationId: update-message-flags-for-narrow
|
|
summary: Update personal message flags for narrow
|
|
tags: ["messages"]
|
|
description: |
|
|
Add or remove personal message flags like `read` and `starred`
|
|
on a range of messages within a narrow.
|
|
|
|
See also [the endpoint for updating flags on specific message
|
|
IDs](/api/update-message-flags).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 155).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- include_anchor
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
anchor:
|
|
allOf:
|
|
- $ref: "#/components/schemas/Anchor"
|
|
- description: |
|
|
Integer message ID to anchor updating of flags. Supports special
|
|
string values for when the client wants the server to compute the anchor
|
|
to use:
|
|
|
|
- `newest`: The most recent message.
|
|
- `oldest`: The oldest message.
|
|
- `first_unread`: The oldest unread message matching the
|
|
query, if any; otherwise, the most recent message.
|
|
example: "43"
|
|
include_anchor:
|
|
description: |
|
|
Whether a message with the specified ID matching the narrow
|
|
should be included in the update range.
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
num_before:
|
|
description: |
|
|
Limit the number of messages preceding the anchor in the
|
|
update range. The server may decrease this to bound
|
|
transaction sizes.
|
|
type: integer
|
|
minimum: 0
|
|
example: 4
|
|
num_after:
|
|
description: |
|
|
Limit the number of messages following the anchor in the
|
|
update range. The server may decrease this to bound
|
|
transaction sizes.
|
|
type: integer
|
|
minimum: 0
|
|
example: 8
|
|
narrow:
|
|
description: |
|
|
The narrow you want update flags within. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
Note that, when adding the `read` flag to messages, clients should
|
|
consider including a narrow with the `is:unread` filter as an
|
|
optimization. Including that filter takes advantage of the fact that
|
|
the server has a database index for unread messages.
|
|
|
|
**Changes**: See [changes section](/api/construct-narrow#changes)
|
|
of search/narrow filter documentation.
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
required:
|
|
- operator
|
|
- operand
|
|
additionalProperties: false
|
|
properties:
|
|
operator:
|
|
type: string
|
|
operand:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
negated:
|
|
type: boolean
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minItems: 2
|
|
maxItems: 2
|
|
default: []
|
|
example: [{"operand": "Denmark", "operator": "channel"}]
|
|
op:
|
|
description: |
|
|
Whether to `add` the flag or `remove` it.
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
flag:
|
|
description: |
|
|
The flag that should be added/removed. See [available
|
|
flags](/api/update-message-flags#available-flags).
|
|
type: string
|
|
example: read
|
|
required:
|
|
- anchor
|
|
- num_before
|
|
- num_after
|
|
- narrow
|
|
- op
|
|
- flag
|
|
encoding:
|
|
include_anchor:
|
|
contentType: application/json
|
|
num_before:
|
|
contentType: application/json
|
|
num_after:
|
|
contentType: application/json
|
|
narrow:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- processed_count
|
|
- updated_count
|
|
- first_processed_id
|
|
- last_processed_id
|
|
- found_oldest
|
|
- found_newest
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
processed_count:
|
|
type: integer
|
|
description: |
|
|
The number of messages that were within the
|
|
update range (at most `num_before + 1 +
|
|
num_after`).
|
|
updated_count:
|
|
type: integer
|
|
description: |
|
|
The number of messages where the flag's
|
|
value was changed (at most
|
|
`processed_count`).
|
|
first_processed_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the oldest message within the
|
|
update range, or `null` if the range was
|
|
empty.
|
|
last_processed_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the newest message within the
|
|
update range, or `null` if the range was
|
|
empty.
|
|
found_oldest:
|
|
type: boolean
|
|
description: |
|
|
Whether the update range reached backward
|
|
far enough to include very oldest message
|
|
matching the narrow (used by clients doing a
|
|
bulk update to decide whether to issue
|
|
another request anchored at
|
|
`first_processed_id`).
|
|
found_newest:
|
|
type: boolean
|
|
description: |
|
|
Whether the update range reached forward far
|
|
enough to include very oldest message
|
|
matching the narrow (used by clients doing a
|
|
bulk update to decide whether to issue
|
|
another request anchored at
|
|
`last_processed_id`).
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"processed_count": 11,
|
|
"updated_count": 8,
|
|
"first_processed_id": 35,
|
|
"last_processed_id": 55,
|
|
"found_oldest": false,
|
|
"found_newest": true,
|
|
}
|
|
/messages/render:
|
|
post:
|
|
operationId: render-message
|
|
summary: Render a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Render a message to HTML.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
content:
|
|
$ref: "#/components/schemas/RequiredContent"
|
|
required:
|
|
- content
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
rendered:
|
|
type: string
|
|
description: |
|
|
The rendered HTML.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"rendered": "<p><strong>foo</strong></p>",
|
|
"result": "success",
|
|
}
|
|
/messages/{message_id}/reactions:
|
|
post:
|
|
operationId: add-reaction
|
|
summary: Add an emoji reaction
|
|
tags: ["messages"]
|
|
description: |
|
|
Add an [emoji reaction](/help/emoji-reactions) to a message.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- emoji_code
|
|
- reaction_type
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
emoji_name:
|
|
description: |
|
|
The target emoji's human-readable name.
|
|
|
|
To find an emoji's name, hover over a message to reveal
|
|
three icons on the right, then click the smiley face icon.
|
|
Images of available reaction emojis appear. Hover over the
|
|
emoji you want, and note that emoji's text name.
|
|
type: string
|
|
example: "octopus"
|
|
emoji_code:
|
|
$ref: "#/components/schemas/EmojiCode"
|
|
reaction_type:
|
|
$ref: "#/components/schemas/ReactionType"
|
|
required:
|
|
- emoji_name
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid emoji code",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the emoji code is invalid:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Reaction already exists.",
|
|
"code": "REACTION_ALREADY_EXISTS",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the reaction already exists.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 193). Previously, this
|
|
error returned the `"BAD_REQUEST"` code.
|
|
delete:
|
|
operationId: remove-reaction
|
|
summary: Remove an emoji reaction
|
|
tags: ["messages"]
|
|
description: |
|
|
Remove an [emoji reaction](/help/emoji-reactions) from a message.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- emoji_code
|
|
- reaction_type
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
emoji_name:
|
|
description: |
|
|
The target emoji's human-readable name.
|
|
|
|
To find an emoji's name, hover over a message to reveal
|
|
three icons on the right, then click the smiley face icon.
|
|
Images of available reaction emojis appear. Hover over the
|
|
emoji you want, and note that emoji's text name.
|
|
type: string
|
|
example: "octopus"
|
|
emoji_code:
|
|
$ref: "#/components/schemas/EmojiCode"
|
|
reaction_type:
|
|
$ref: "#/components/schemas/ReactionType"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid emoji code",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the emoji code is invalid:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Reaction doesn't exist.",
|
|
"code": "REACTION_DOES_NOT_EXIST",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the reaction does not exist.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 193). Previously, this
|
|
error returned the `"BAD_REQUEST"` code.
|
|
|
|
/messages/{message_id}/read_receipts:
|
|
get:
|
|
operationId: get-read-receipts
|
|
summary: Get a message's read receipts
|
|
tags: ["messages"]
|
|
description: |
|
|
Returns a list containing the IDs for all users who have
|
|
marked the message as read (and whose privacy settings allow
|
|
sharing that information).
|
|
|
|
The list of users IDs will include any bots who have marked
|
|
the message as read via the API (providing a way for bots to
|
|
indicate whether they have processed a message successfully in
|
|
a way that can be easily inspected in a Zulip client). Bots
|
|
for which this behavior is not desired may disable the
|
|
`send_read_receipts` setting via the API.
|
|
|
|
It will never contain the message's sender.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
An array of IDs of users who have marked the target message as
|
|
read and whose read status is available to the current user.
|
|
|
|
The IDs of users who have disabled sending read receipts
|
|
(`"send_read_receipts": false`) will never appear in the response,
|
|
nor will the message's sender. Additionally, the IDs of any users
|
|
who have been muted by the current user or who have muted the
|
|
current user will not be included in the response.
|
|
|
|
The current user's ID will appear if they have marked the target
|
|
message as read.
|
|
|
|
**Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of
|
|
users who have been muted by or have muted the current user were
|
|
included in the response.
|
|
items:
|
|
type: integer
|
|
example:
|
|
{"msg": "", "result": "success", "user_ids": [3, 7, 9]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
A typical JSON response when attempting to access read receipts for
|
|
a message ID that either does not exist or is not accessible to the
|
|
current user:
|
|
/messages/matches_narrow:
|
|
get:
|
|
operationId: check-messages-match-narrow
|
|
summary: Check if messages match a narrow
|
|
tags: ["messages"]
|
|
description: |
|
|
Check whether a set of messages match a [narrow](/api/construct-narrow).
|
|
|
|
For many common narrows (e.g. a topic), clients can write an efficient
|
|
client-side check to determine whether a newly arrived message belongs
|
|
in the view.
|
|
|
|
This endpoint is designed to allow clients to handle more complex narrows
|
|
for which the client does not (or in the case of full-text search, cannot)
|
|
implement this check.
|
|
|
|
The format of the `match_subject` and `match_content` objects is designed
|
|
to match those returned by the [`GET /messages`](/api/get-messages#response)
|
|
endpoint, so that a client can splice these fields into a `message` object
|
|
received from [`GET /events`](/api/get-events#message) and end up with an
|
|
extended message object identical to how a [`GET /messages`](/api/get-messages)
|
|
request for the current narrow would have returned the message.
|
|
parameters:
|
|
- name: msg_ids
|
|
in: query
|
|
description: List of IDs for the messages to check.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [31, 32]
|
|
required: true
|
|
- name: narrow
|
|
in: query
|
|
description: |
|
|
A structure defining the narrow to check against. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
**Changes**: See [changes section](/api/construct-narrow#changes)
|
|
of search/narrow filter documentation.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example: [{"operator": "has", "operand": "link"}]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
messages:
|
|
type: object
|
|
description: |
|
|
A dictionary with a key for each queried message that matches the narrow,
|
|
with message IDs as keys and search rendering data as values.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
match_content:
|
|
type: string
|
|
description: |
|
|
HTML content of a queried message that matches the narrow. If the
|
|
narrow is a search narrow, `<span class="highlight">` elements
|
|
will be included, wrapping the matches for the search keywords.
|
|
match_subject:
|
|
type: string
|
|
description: |
|
|
HTML-escaped topic of a queried message that matches the narrow. If the
|
|
narrow is a search narrow, `<span class="highlight">` elements
|
|
will be included wrapping the matches for the search keywords.
|
|
description: |
|
|
`message_id`: The ID of the message that matches the narrow. No record will be returned
|
|
for queried messages that do not match the narrow.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"messages":
|
|
{
|
|
"31":
|
|
{
|
|
"match_content": '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
|
|
"match_subject": "test_topic",
|
|
},
|
|
},
|
|
}
|
|
/messages/{message_id}:
|
|
get:
|
|
operationId: get-message
|
|
summary: Fetch a single message
|
|
tags: ["messages"]
|
|
description: |
|
|
Given a message ID, return the message object.
|
|
|
|
Additionally, a `raw_content` field is included. This field is
|
|
useful for clients that primarily work with HTML-rendered
|
|
messages but might need to occasionally fetch the message's
|
|
raw Markdown (e.g. for [view
|
|
source](/help/view-the-markdown-source-of-a-message) or
|
|
prefilling a message edit textarea).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 120), this
|
|
endpoint only returned the `raw_content` field.
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- name: apply_markdown
|
|
in: query
|
|
description: |
|
|
If `true`, message content is returned in the rendered HTML
|
|
format. If `false`, message content is returned in the raw
|
|
Markdown-format text that user entered.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 120).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
raw_content:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The raw Markdown content of the message.
|
|
|
|
**Deprecated** and to be removed once no longer required for
|
|
legacy clients. Modern clients should prefer passing
|
|
`"apply_markdown": false` to request raw message content.
|
|
message:
|
|
description: |
|
|
An object containing details of the message.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 120).
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
|
|
flag was deprecated in favor of the `stream_wildcard_mentioned` and
|
|
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
|
|
for backwards compatibility with older clients and equals
|
|
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
|
|
supporting older server versions should treat this field as a previous
|
|
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
|
|
were not available prior to this feature level.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"raw_content": "**Don't** forget your towel!",
|
|
"result": "success",
|
|
"msg": "",
|
|
"message":
|
|
{
|
|
"subject": "",
|
|
"sender_realm_str": "zulip",
|
|
"type": "private",
|
|
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
|
|
"flags": ["read"],
|
|
"id": 16,
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"id": 4,
|
|
"is_mirror_dummy": false,
|
|
"email": "hamlet@zulip.com",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
{
|
|
"id": 5,
|
|
"is_mirror_dummy": false,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago",
|
|
},
|
|
{
|
|
"id": 8,
|
|
"is_mirror_dummy": false,
|
|
"email": "prospero@zulip.com",
|
|
"full_name": "Prospero from The Tempest",
|
|
},
|
|
],
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527921326,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 27,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist or it
|
|
is not visible to the user making the query (e.g. it was a direct message
|
|
between two other users):
|
|
patch:
|
|
operationId: update-message
|
|
summary: Edit a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Update the content, topic, or channel of the message with the specified
|
|
ID.
|
|
|
|
You can [resolve topics](/help/resolve-a-topic) by editing the topic to
|
|
`✔ {original_topic}` with the `propagate_mode` parameter set to
|
|
`"change_all"`.
|
|
|
|
See [configuring message editing][config-message-editing] for detailed
|
|
documentation on when users are allowed to edit message content, and
|
|
[restricting moving messages][restrict-move-messages] for detailed
|
|
documentation on when users are allowed to change a message's topic
|
|
and/or channel.
|
|
|
|
The relevant realm settings in the API that are related to the above
|
|
linked documentation on when users are allowed to update messages are:
|
|
|
|
- `allow_message_editing`
|
|
- `can_move_messages_between_channels_group`
|
|
- `can_move_messages_between_topics_group`
|
|
- `message_content_edit_limit_seconds`
|
|
- `move_messages_within_stream_limit_seconds`
|
|
- `move_messages_between_streams_limit_seconds`
|
|
|
|
More details about these realm settings can be found in the
|
|
[`POST /register`](/api/register-queue) response or in the documentation
|
|
of the [`realm op: update_dict`](/api/get-events#realm-update_dict)
|
|
event in [`GET /events`](/api/get-events).
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 316), `edit_topic_policy`
|
|
was removed and replaced by `can_move_messages_between_topics_group`
|
|
realm setting.
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 310), `move_messages_between_streams_policy`
|
|
was removed and replaced by `can_move_messages_between_channels_group`
|
|
realm setting.
|
|
|
|
Prior to Zulip 7.0 (feature level 172), anyone could add a
|
|
topic to channel messages without a topic, regardless of the organization's
|
|
[topic editing permissions](/help/restrict-moving-messages). As of this
|
|
feature level, messages without topics have the same restrictions for
|
|
topic edits as messages with topics.
|
|
|
|
Before Zulip 7.0 (feature level 172), by using the `change_all` value for
|
|
the `propagate_mode` parameter, users could move messages after the
|
|
organization's configured time limits for changing a message's topic or
|
|
channel had passed. As of this feature level, the server will [return an
|
|
error](/api/update-message#response) with `"code":
|
|
"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"` if users, other than organization
|
|
administrators or moderators, try to move messages after these time
|
|
limits have passed.
|
|
|
|
Before Zulip 7.0 (feature level 162), users who were not administrators or
|
|
moderators could only edit topics if the target message was sent within the
|
|
last 3 days. As of this feature level, that time limit is now controlled by
|
|
the realm setting `move_messages_within_stream_limit_seconds`. Also at this
|
|
feature level, a similar time limit for moving messages between channels was
|
|
added, controlled by the realm setting
|
|
`move_messages_between_streams_limit_seconds`. Previously, all users who
|
|
had permission to move messages between channels did not have any time limit
|
|
restrictions when doing so.
|
|
|
|
Before Zulip 7.0 (feature level 159), editing channels and topics of messages
|
|
was forbidden if the realm setting for `allow_message_editing` was `false`,
|
|
regardless of an organization's configuration for the realm settings
|
|
`edit_topic_policy` or `move_messages_between_streams_policy`.
|
|
|
|
Before Zulip 7.0 (feature level 159), message senders were allowed to edit
|
|
the topic of their messages indefinitely.
|
|
|
|
In Zulip 5.0 (feature level 75), the `edit_topic_policy` realm setting
|
|
was added, replacing the `allow_community_topic_editing` boolean.
|
|
|
|
In Zulip 4.0 (feature level 56), the `move_messages_between_streams_policy`
|
|
realm setting was added.
|
|
|
|
[config-message-editing]: /help/restrict-message-editing-and-deletion
|
|
[restrict-move-messages]: /help/restrict-moving-messages
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- stream_id
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
topic:
|
|
description: |
|
|
The topic to move the message(s) to, to request changing the topic.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length
|
|
|
|
Should only be sent when changing the topic, and will throw an error
|
|
if the target message is not a channel message.
|
|
|
|
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
|
|
this as `subject`, which is currently a deprecated alias.
|
|
type: string
|
|
example: Castle
|
|
propagate_mode:
|
|
description: |
|
|
Which message(s) should be edited:
|
|
|
|
- `"change_later"`: The target message and all following messages.
|
|
- `"change_one"`: Only the target message.
|
|
- `"change_all"`: All messages in this topic.
|
|
|
|
Only the default value of `"change_one"` is valid when editing
|
|
only the content of a message.
|
|
|
|
This parameter determines both which messages get moved and also whether
|
|
clients that are currently narrowed to the topic containing the message
|
|
should navigate or adjust their compose box recipient to point to the
|
|
post-edit channel/topic.
|
|
type: string
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
default: change_one
|
|
example: change_all
|
|
send_notification_to_old_thread:
|
|
description: |
|
|
Whether to send an automated message to the old topic to
|
|
notify users where the messages were moved to.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
|
|
had a default of `true` and was ignored unless the channel was changed.
|
|
|
|
New in Zulip 3.0 (feature level 9).
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
send_notification_to_new_thread:
|
|
description: |
|
|
Whether to send an automated message to the new topic to
|
|
notify users where the messages came from.
|
|
|
|
If the move is just [resolving/unresolving a topic](/help/resolve-a-topic),
|
|
this parameter will not trigger an additional notification.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
|
|
was ignored unless the channel was changed.
|
|
|
|
New in Zulip 3.0 (feature level 9).
|
|
type: boolean
|
|
default: true
|
|
example: true
|
|
content:
|
|
$ref: "#/components/schemas/OptionalContent"
|
|
stream_id:
|
|
description: |
|
|
The channel ID to move the message(s) to, to request moving
|
|
messages to another channel.
|
|
|
|
Should only be sent when changing the channel, and will throw an error
|
|
if the target message is not a channel message.
|
|
|
|
Note that a message's content and channel cannot be changed at the
|
|
same time, so sending both `content` and `stream_id` parameters will
|
|
throw an error.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
type: integer
|
|
example: 43
|
|
encoding:
|
|
send_notification_to_old_thread:
|
|
contentType: application/json
|
|
send_notification_to_new_thread:
|
|
contentType: application/json
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
detached_uploads:
|
|
type: array
|
|
description: |
|
|
Details on all files uploaded by the acting user whose only references
|
|
were removed when editing this message. Clients should ask the acting user
|
|
if they wish to delete the uploaded files returned in this response,
|
|
which might otherwise remain visible only in message edit history.
|
|
|
|
Note that [access to message edit
|
|
history](/help/disable-message-edit-history) is configurable; this detail
|
|
may be important in presenting the question clearly to users.
|
|
|
|
New in Zulip 10.0 (feature level 285).
|
|
items:
|
|
$ref: "#/components/schemas/Attachments"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"detached_uploads":
|
|
[
|
|
{
|
|
"id": 3,
|
|
"name": "1253601-1.jpg",
|
|
"path_id": "2/5d/BD5NRptFxPDKY3RUKwhhup8r/1253601-1.jpg",
|
|
"size": 1339060,
|
|
"create_time": 1687984706000,
|
|
"messages": [],
|
|
},
|
|
],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- properties:
|
|
msg:
|
|
enum:
|
|
- Your organization has turned off message editing
|
|
- You don't have permission to edit this message
|
|
- The time limit for editing this message has past
|
|
- Nothing to change
|
|
- Topic can't be empty
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to edit this message",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical JSON response for when one doesn't have the permission to
|
|
edit a particular message:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED",
|
|
"first_message_id_allowed_to_move": 123,
|
|
"msg": "You only have permission to move the 2/5 most recent messages in this topic.",
|
|
"result": "error",
|
|
"total_messages_allowed_to_move": 2,
|
|
"total_messages_in_topic": 5,
|
|
}
|
|
description: |
|
|
A special failed JSON response (`"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"`)
|
|
for when the user has permission to move
|
|
the target message, but asked to move all messages in a topic
|
|
(`"propagate_mode": "change_all"`) and the user does not have permission
|
|
to move the entire topic.
|
|
|
|
This happens when the topic contains some messages that are older than an
|
|
applicable time limit for the requested topic move (see
|
|
`move_messages_within_stream_limit_seconds` and/or
|
|
`move_messages_between_streams_limit_seconds` in the
|
|
[`POST /register`](/api/register-queue) response).
|
|
|
|
The error response contains data on which portion of this topic the user has
|
|
permission to move. `first_message_id_allowed_to_move` is the oldest message
|
|
ID in this topic that the user has permission to move.
|
|
There are `total_messages_in_topic` in the topic, but the user only has
|
|
permission to move the (most recent) `total_messages_allowed_to_move`
|
|
messages.
|
|
|
|
Clients should support this error code with
|
|
`"first_message_id_allowed_to_move": null` for forward compatibility
|
|
with future server versions that may use this error code with other
|
|
propagation modes where the user does not have permission to move any
|
|
messages, or where the server did not calculate the total message counts
|
|
noted above.
|
|
|
|
Clients can either only present the error to the user or, if
|
|
`first_message_id_allowed_to_move` is not `null`, prompt the user to adjust
|
|
their query with the above information.
|
|
|
|
If clients choose to present a prompt for this error code, they should
|
|
recommend the option of cancelling and (manually) asking a moderator to
|
|
move the entire topic, since that's often a better experience than
|
|
partially moving a topic. This API supports a client that wishes to allow
|
|
the user to repeat the request with a `change_later` propagation mode and
|
|
a target message ID of `first_message_id_allowed_to_move`, if the user
|
|
desires to move only the portion of the topic that they can.
|
|
|
|
Note that in a channel with [protected history](/help/channel-permissions),
|
|
the Zulip security model requires that the above calculations only include
|
|
messages the acting user has access to. So in the rare case of a user
|
|
attempting to move a topic that started before the user joined a private
|
|
channel with protected history, this API endpoint might move only the portion
|
|
of a topic that they have access to, without this error or any confirmation
|
|
dialog.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 172).
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "You do not have permission to use channel wildcard mentions in this channel.",
|
|
"code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the message was rejected because
|
|
of the organization's `wildcard_mention_policy` and large number of
|
|
subscribers to the channel.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 229). Previously, this
|
|
error returned the `"BAD_REQUEST"` code.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "You do not have permission to use topic wildcard mentions in this topic.",
|
|
"code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the message was rejected because
|
|
the message contains a topic wildcard mention, but the user doesn't have
|
|
permission to use such a mention in this topic due to the
|
|
`wildcard_mention_policy` (and large number of participants in this
|
|
specific topic).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 229). Previously,
|
|
`wildcard_mention_policy` was not enforced for topic mentions.
|
|
delete:
|
|
operationId: delete-message
|
|
summary: Delete a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Permanently delete a message.
|
|
|
|
This API corresponds to the
|
|
[delete a message completely][delete-completely] feature documented in
|
|
the Zulip Help Center.
|
|
|
|
[delete-completely]: /help/delete-a-message#delete-a-message-completely
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
An example JSON response for when the user making the query does not
|
|
have permission to delete the message:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to delete this message",
|
|
"result": "error",
|
|
}
|
|
/user_uploads:
|
|
post:
|
|
operationId: upload-file
|
|
summary: Upload a file
|
|
tags: ["messages"]
|
|
description: |
|
|
Upload a single file and get the corresponding URL.
|
|
|
|
Initially, only you will be able to access the link. To share the
|
|
uploaded file, you'll need to [send a message][send-message]
|
|
containing the resulting link. Users who can already access the link
|
|
can reshare it with other users by sending additional Zulip messages
|
|
containing the link.
|
|
|
|
For uploading larger files, `/api/v1/tus` is an endpoint
|
|
implementing the [`tus`
|
|
protocol](https://tus.io/protocols/resumable-upload) for
|
|
resumable uploads. Clients which send authenticated
|
|
credentials (either via browser-based cookies, or API key via
|
|
`Authorization` header) may use this endpoint to create
|
|
uploads.
|
|
|
|
[uploaded-files]: /help/manage-your-uploaded-files
|
|
[send-message]: /api/send-message
|
|
x-parameter-description: |
|
|
As described above, the file to upload must be provided in the
|
|
request's body.
|
|
|
|
## Maximum file size
|
|
|
|
The maximum file size for uploads can be configured by the
|
|
administrator of the Zulip server by setting `MAX_FILE_UPLOAD_SIZE`
|
|
in the [server's settings][1]. `MAX_FILE_UPLOAD_SIZE` defaults
|
|
to 100MB.
|
|
|
|
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
filename:
|
|
type: string
|
|
format: binary
|
|
example: /path/to/file
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
uri:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The URL of the uploaded file. Alias of `url`.
|
|
|
|
**Changes**: Deprecated in Zulip 9.0 (feature level 272). The term
|
|
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
|
|
url:
|
|
type: string
|
|
description: |
|
|
The URL of the uploaded file.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 272). Previously,
|
|
this property was only available under the legacy `uri` name.
|
|
filename:
|
|
type: string
|
|
description: |
|
|
The filename that Zulip stored the upload as. This usually
|
|
differs from the basename of the URL when HTML escaping is
|
|
required to generate a valid URL.
|
|
|
|
Clients generating a Markdown link to a newly uploaded file
|
|
should do so by combining the `url` and `filename` fields in the
|
|
response as follows: `[{filename}]({url})`, with care taken to
|
|
clean `filename` of `[` and `]` characters that might break
|
|
Markdown rendering.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 285).
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
|
|
"url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
|
|
"filename": "zulip.txt",
|
|
}
|
|
/user_uploads/{realm_id_str}/{filename}:
|
|
get:
|
|
operationId: get-file-temporary-url
|
|
summary: Get public temporary URL
|
|
tags: ["messages"]
|
|
description: |
|
|
Get a temporary URL for access to the file that doesn't require authentication.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
parameters:
|
|
- name: realm_id_str
|
|
in: path
|
|
description: |
|
|
The realm ID.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
- name: filename
|
|
in: path
|
|
description: |
|
|
Path to the URL.
|
|
schema:
|
|
type: string
|
|
example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
url:
|
|
type: string
|
|
description: |
|
|
A temporary URL that can be used to access the uploaded file
|
|
without Zulip's normal API authentication.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55",
|
|
}
|
|
|
|
/users:
|
|
get:
|
|
operationId: get-users
|
|
summary: Get all users
|
|
tags: ["users"]
|
|
description: |
|
|
Retrieve details on all users in the organization. Optionally
|
|
includes values of [custom profile fields](/help/custom-profile-fields).
|
|
|
|
You can also [fetch details on a single user](/api/get-user).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` query parameter as follows:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
members:
|
|
type: array
|
|
description: |
|
|
A list of `user` objects, each containing details about a user in the
|
|
organization.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"members":
|
|
[
|
|
{
|
|
"is_active": true,
|
|
"email": "AARON@zulip.com",
|
|
"delivery_email": null,
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_bot": false,
|
|
"user_id": 7,
|
|
"profile_data": {},
|
|
"is_guest": false,
|
|
"date_joined": "2019-10-20T07:50:53.728864+00:00",
|
|
"full_name": "aaron",
|
|
},
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
{
|
|
"bot_owner_id": 11,
|
|
"is_guest": false,
|
|
"date_joined": "2019-10-20T12:52:17.862053+00:00",
|
|
"full_name": "Iago's Bot",
|
|
"email": "iago-bot@zulipdev.com",
|
|
"delivery_email": "iago-bot@zulipdev.com",
|
|
"is_active": true,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"user_id": 23,
|
|
"bot_type": 1,
|
|
"timezone": "",
|
|
"is_bot": true,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-user
|
|
summary: Create a user
|
|
tags: ["users"]
|
|
description: |
|
|
Create a new user account via the API.
|
|
|
|
!!! warn ""
|
|
|
|
**Note**: On Zulip Cloud, this feature is available only for
|
|
organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)
|
|
or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators
|
|
can request the required `can_create_users` permission for a bot or
|
|
user by contacting [Zulip Cloud support][support] with an
|
|
explanation for why it is needed. Self-hosted installations can
|
|
toggle `can_create_users` on an account using the `manage.py
|
|
change_user_role` [management command][management-commands].
|
|
|
|
**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was
|
|
available to all organization administrators.
|
|
|
|
[support]: /help/contact-support
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
x-requires-administrator: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
description: |
|
|
The email address of the new user.
|
|
type: string
|
|
example: username@example.com
|
|
password:
|
|
description: |
|
|
The password of the new user.
|
|
type: string
|
|
example: abcd1234
|
|
full_name:
|
|
description: |
|
|
The full name of the new user.
|
|
type: string
|
|
example: New User
|
|
required:
|
|
- email
|
|
- password
|
|
- full_name
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID assigned to the newly created user.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
example: {"msg": "", "result": "success", "user_id": 25}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Email 'newbie@zulip.com' already in use",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical JSON response for when another user with the same
|
|
email address already exists in the realm:
|
|
/users/{user_id}/reactivate:
|
|
post:
|
|
operationId: reactivate-user
|
|
summary: Reactivate a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
[Reactivates a
|
|
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
|
|
given their user ID.
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
/users/{user_id}/status:
|
|
get:
|
|
operationId: get-user-status
|
|
summary: Get a user's status
|
|
tags: ["users"]
|
|
description: |
|
|
Get the [status](/help/status-and-availability) currently set by a
|
|
user in the organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 262). Previously,
|
|
user statuses could only be fetched via the [`POST
|
|
/register`](/api/register-queue) endpoint.
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
status:
|
|
allOf:
|
|
- description: |
|
|
The status set by the user. Note that, if the user doesn't have a status
|
|
currently set, then the returned dictionary will be empty as none of the
|
|
keys listed below will be present.
|
|
- $ref: "#/components/schemas/UserStatus"
|
|
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"status":
|
|
{
|
|
"status_text": "on vacation",
|
|
"emoji_name": "car",
|
|
"emoji_code": "1f697",
|
|
"reaction_type": "unicode_emoji",
|
|
},
|
|
}
|
|
"400":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "No such user",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the user does not exist:
|
|
/users/{user_id_or_email}/presence:
|
|
get:
|
|
operationId: get-user-presence
|
|
summary: Get a user's presence
|
|
tags: ["users"]
|
|
description: |
|
|
Get the presence status for a specific user.
|
|
|
|
This endpoint is most useful for embedding data about a user's
|
|
presence status in other sites (e.g. an employee directory). Full
|
|
Zulip clients like mobile/desktop apps will want to use the [main
|
|
presence endpoint](/api/get-presence), which returns data for all
|
|
active users in the organization, instead.
|
|
|
|
See [Zulip's developer documentation][subsystems-presence]
|
|
for details on the data model for presence in Zulip.
|
|
|
|
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
|
|
parameters:
|
|
- name: user_id_or_email
|
|
in: path
|
|
description: |
|
|
The ID or Zulip API email address of the user whose presence you want to fetch.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported
|
|
identifying the user by Zulip API email.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
presence:
|
|
type: object
|
|
description: |
|
|
An object containing the presence details for the user.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
When this update was received. If the timestamp
|
|
is more than a few minutes in the past, the user is offline.
|
|
status:
|
|
type: string
|
|
description: |
|
|
Whether the user had recently interacted with Zulip at the time
|
|
of the timestamp.
|
|
|
|
Will be either `"active"` or `"idle"`
|
|
description: |
|
|
`{client_name}` or `"aggregated"`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
|
|
contain two keys, `"website"` and `"aggregated"`, with identical data. The
|
|
server no longer stores which client submitted presence updates.
|
|
|
|
Previously, the `{client_name}` keys for these objects were the names of the
|
|
different clients where the user was logged in, for example `website` or
|
|
`ZulipDesktop`.
|
|
example:
|
|
{
|
|
"presence":
|
|
{
|
|
"website":
|
|
{"timestamp": 1532697622, "status": "active"},
|
|
"aggregated":
|
|
{"timestamp": 1532697622, "status": "active"},
|
|
},
|
|
"result": "success",
|
|
"msg": "",
|
|
}
|
|
/users/me:
|
|
get:
|
|
operationId: get-own-user
|
|
summary: Get own user
|
|
tags: ["users"]
|
|
description: |
|
|
Get basic data about the user/bot that requests this endpoint.
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
URL for the requesting user's avatar.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
example: "x"
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
Version for the requesting user's avatar. Used for cache-busting requests
|
|
for the user's avatar. Clients generally shouldn't need to use this;
|
|
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: 1
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the requesting user.
|
|
example: "iago@zulip.com"
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the requesting user.
|
|
example: "Iago"
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is an admin.
|
|
example: true
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is
|
|
an organization owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8).
|
|
example: false
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is
|
|
a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
example: false
|
|
role:
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
description: |
|
|
[Organization-level role](/api/roles-and-permissions) of
|
|
the requesting user.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is a guest.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: false
|
|
is_bot:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is a bot.
|
|
example: false
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the requesting user account
|
|
has been deactivated.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: true
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The time zone of the requesting user.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: ""
|
|
date_joined:
|
|
type: string
|
|
description: |
|
|
The time the requesting user's account was created.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: "2019-10-20T07:50:53.728864+00:00"
|
|
max_message_id:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
The integer ID of the last message received by the requesting
|
|
user's account.
|
|
|
|
**Deprecated**. We plan to remove this in favor of recommending
|
|
using `GET /messages` with `"anchor": "newest"`.
|
|
example: 30
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
example: 1
|
|
delivery_email:
|
|
type: string
|
|
description: |
|
|
The requesting user's real email address.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
|
|
present only when `email_address_visibility` was restricted and the
|
|
requesting user had permission to access realm users' emails. As of
|
|
this feature level, this field is always present.
|
|
profile_data:
|
|
$ref: "#/components/schemas/profile_data"
|
|
example:
|
|
{
|
|
"avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1",
|
|
"avatar_version": 1,
|
|
"email": "iago@zulip.com",
|
|
"delivery_email": iago@zulip.com,
|
|
"full_name": "Iago",
|
|
"is_admin": true,
|
|
"is_owner": false,
|
|
"role": 200,
|
|
"is_guest": false,
|
|
"is_billing_admin": false,
|
|
"is_bot": false,
|
|
"is_active": true,
|
|
"timezone": "",
|
|
"date_joined": "2019-10-20T07:50:53.728864+00:00",
|
|
"max_message_id": 30,
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_id": 5,
|
|
"profile_data":
|
|
{
|
|
"5": {"value": "2000-01-01"},
|
|
"4": {"value": "emacs"},
|
|
"7": {"value": "[10]"},
|
|
"1":
|
|
{
|
|
"value": "+1-234-567-8901",
|
|
"rendered_value": "<p>+1-234-567-8901</p>",
|
|
},
|
|
"2":
|
|
{
|
|
"rendered_value": "<p>Betrayer of Othello.</p>",
|
|
"value": "Betrayer of Othello.",
|
|
},
|
|
"8": {"value": "zulip"},
|
|
"3":
|
|
{
|
|
"value": "Apples",
|
|
"rendered_value": "<p>Apples</p>",
|
|
},
|
|
"6":
|
|
{
|
|
"value": "https://zulip.readthedocs.io/en/latest/",
|
|
},
|
|
},
|
|
}
|
|
delete:
|
|
operationId: deactivate-own-user
|
|
summary: Deactivate own user
|
|
tags: ["users"]
|
|
description: |
|
|
Deactivates the current user's account. See also the administrative endpoint for
|
|
[deactivating another user](/api/deactivate-user).
|
|
|
|
This endpoint is primarily useful to Zulip clients providing a user settings UI.
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
entity:
|
|
type: string
|
|
description: |
|
|
An internationalized string that notes if the current user is the only
|
|
organization owner or the only user in the organization.
|
|
is_last_owner:
|
|
type: boolean
|
|
description: |
|
|
Whether the current user is the only organization owner (meaning there
|
|
are other active users in the organization) or the only active user in the
|
|
organization.
|
|
required:
|
|
- entity
|
|
- is_last_owner
|
|
example:
|
|
{
|
|
"code": "CANNOT_DEACTIVATE_LAST_USER",
|
|
"msg": "Cannot deactivate the only organization owner",
|
|
"result": "error",
|
|
"entity": "organization owner",
|
|
"is_last_owner": true,
|
|
}
|
|
description: |
|
|
If the current user is the only organization owner or only user in the
|
|
organization, their account cannot be deactivated and an error response
|
|
will be returned. The `is_last_owner` field in the error response
|
|
indicates whether the user is the only owner (`true`) or the only user
|
|
(`false`). The `entity` field in the error response is a internationalized
|
|
string that notes if the current user is the only organization owner or
|
|
the only user.
|
|
|
|
An example JSON error response when the current user is the only
|
|
organization owner in the organization:
|
|
/users/me/alert_words:
|
|
get:
|
|
operationId: get-alert-words
|
|
summary: Get all alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Get all of the user's configured [alert words][alert-words].
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["natural", "illustrious"],
|
|
}
|
|
post:
|
|
operationId: add-alert-words
|
|
summary: Add alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Add words (or phrases) to the user's set of configured [alert words][alert-words].
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
alert_words:
|
|
description: |
|
|
An array of strings to be added to the user's set of configured
|
|
alert words. Strings already present in the user's set of alert words
|
|
already are ignored.
|
|
|
|
Alert words are case insensitive.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["foo", "bar"]
|
|
required:
|
|
- alert_words
|
|
encoding:
|
|
alert_words:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["foo", "bar", "natural", "illustrious"],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "alert_words[0] is too long (limit: 100 characters)",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when a supplied alert word (or phrase)
|
|
exceeds the character limit:
|
|
delete:
|
|
operationId: remove-alert-words
|
|
summary: Remove alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Remove words (or phrases) from the user's set of configured [alert words][alert-words].
|
|
|
|
Alert words are case insensitive.
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
alert_words:
|
|
description: |
|
|
An array of strings to be removed from the user's set of configured
|
|
alert words. Strings that are not in the user's set of alert words
|
|
are ignored.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["foo"]
|
|
required:
|
|
- alert_words
|
|
encoding:
|
|
alert_words:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["bar", "natural", "illustrious"],
|
|
}
|
|
/users/me/presence:
|
|
post:
|
|
operationId: update-presence
|
|
summary: Update your presence
|
|
tags: ["users"]
|
|
description: |
|
|
Update the current user's [presence][availability] and fetch presence data
|
|
of other users in the organization.
|
|
|
|
This endpoint is meant to be used by clients for both:
|
|
|
|
- Reporting the current user's presence status (`"active"` or `"idle"`)
|
|
to the server.
|
|
|
|
- Obtaining the presence data of all other users in the organization via
|
|
regular polling (in parallel with receiving
|
|
[`presence` events](/api/get-events#presence)).
|
|
|
|
Accurate user presence is one of the most expensive parts of any
|
|
chat application (in terms of bandwidth and other resources). Therefore,
|
|
it is important that clients implementing Zulip's user presence system
|
|
use the modern [`last_update_id`](#parameter-last_update_id) protocol to
|
|
minimize fetching duplicate user presence data.
|
|
|
|
See [Zulip's developer documentation][subsystems-presence] for details
|
|
on the data model for user presence in Zulip.
|
|
|
|
The Zulip server is responsible for implementing [invisible mode][invisible],
|
|
which disables sharing a user's presence data. Nonetheless, clients
|
|
should check the `presence_enabled` field in user objects in order to
|
|
display the current user as online or offline based on whether they are
|
|
sharing their presence information.
|
|
|
|
**Changes**: As of Zulip 8.0 (feature level 228), if the
|
|
`CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is
|
|
`true`, then user presence data in the response is [limited to users
|
|
the current user can see/access][limit-visibility].
|
|
|
|
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
|
|
[limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users
|
|
[invisible]: /help/status-and-availability#invisible-mode
|
|
[availability]: /help/status-and-availability#availability
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
last_update_id:
|
|
type: integer
|
|
description: |
|
|
The identifier that specifies what presence data the client already
|
|
has received, which allows the server to only return more recent
|
|
user presence data.
|
|
|
|
This should be set to `-1` during initialization of the client in
|
|
order to fetch all user presence data, unless the client is obtaining
|
|
initial user presence metadata from the
|
|
[`POST /register`](/api/register-queue) endpoint.
|
|
|
|
In subsequent queries to this endpoint, this value should be set to the
|
|
most recent value of `presence_last_update_id` returned by the server
|
|
in this endpoint's response, which implements incremental fetching
|
|
of user presence data.
|
|
|
|
When this parameter is passed, the user presence data in the response
|
|
will always be in the modern format.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 263). Previously, the
|
|
server sent user presence data for all users who had been active in the
|
|
last two weeks unconditionally.
|
|
example: 5
|
|
history_limit_days:
|
|
type: integer
|
|
description: |
|
|
Limits how far back in time to fetch user presence data. If not specified,
|
|
defaults to 14 days. A value of N means that the oldest presence data
|
|
fetched will be from at most N days ago.
|
|
|
|
Note that this is only useful during the initial user presence data fetch,
|
|
as subsequent fetches should use the `last_update_id` parameter, which
|
|
will act as the limit on how much presence data is returned. `history_limit_days`
|
|
is ignored if `last_update_id` is passed with a value greater than `0`,
|
|
indicating that the client already has some presence data.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 288).
|
|
example: 365
|
|
new_user_input:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has interacted with the client (e.g. moved the mouse,
|
|
used the keyboard, etc.) since the previous presence request from this
|
|
client.
|
|
|
|
The server uses data from this parameter to implement certain [usage
|
|
statistics](/help/analytics).
|
|
|
|
User interface clients that might run in the background, without the
|
|
user ever interacting with them, should be careful to only pass `true`
|
|
if the user has actually interacted with the client in order to avoid
|
|
corrupting usage statistics graphs.
|
|
example: false
|
|
default: false
|
|
ping_only:
|
|
type: boolean
|
|
description: |
|
|
Whether the client is sending a ping-only request, meaning it only
|
|
wants to update the user's presence `status` on the server.
|
|
|
|
Otherwise, also requests the server return user presence data for all
|
|
users in the organization, which is further specified by the
|
|
[`last_update_id`](#parameter-last_update_id) parameter.
|
|
example: false
|
|
default: false
|
|
slim_presence:
|
|
type: boolean
|
|
description: |
|
|
Legacy parameter for configuring the format (modern or legacy) in
|
|
which the server will return user presence data for the organization.
|
|
|
|
Modern clients should use
|
|
[`last_update_id`](#parameter-last_update_id), which guarantees that
|
|
user presence data will be returned in the modern format, and
|
|
should not pass this parameter as `true` unless interacting with an
|
|
older server.
|
|
|
|
Legacy clients that do not yet support `last_update_id` may use the
|
|
value of `true` to request the modern format for user presence data.
|
|
|
|
**Note**: The legacy format for user presence data will be removed
|
|
entirely in a future release.
|
|
|
|
**Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using
|
|
the modern `last_update_id` parameter is the recommended way to
|
|
request the modern format for user presence data.
|
|
|
|
New in Zulip 3.0 (no feature level as it was an unstable API at that
|
|
point).
|
|
example: false
|
|
default: false
|
|
deprecated: true
|
|
status:
|
|
type: string
|
|
enum:
|
|
- idle
|
|
- active
|
|
description: |
|
|
The status of the user on this client.
|
|
|
|
Clients should report the user as `"active"` on this device if the client
|
|
knows that the user is presently using the device (and thus would
|
|
potentially see a notification immediately), even if the user
|
|
has not directly interacted with the Zulip client.
|
|
|
|
Otherwise, it should report the user as `"idle"`.
|
|
|
|
See the related [`new_user_input`](#parameter-new_user_input) parameter
|
|
for how a client should report whether the user is actively using the
|
|
Zulip client.
|
|
example: active
|
|
required:
|
|
- status
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
presence_last_update_id:
|
|
type: integer
|
|
description: |
|
|
The identifier for the latest user presence data returned in
|
|
the `presences` data of the response.
|
|
|
|
If a value was passed for `last_update_id`, then this is
|
|
guaranteed to be equal to or greater than that value. If it
|
|
is the same value, then that indicates to the client that
|
|
there were no updates to previously received user presence
|
|
data.
|
|
|
|
The client should then pass this value as the `last_update_id`
|
|
parameter when it next queries this endpoint, in order to only
|
|
receive new user presence data and avoid redundantly fetching
|
|
already known information.
|
|
|
|
This will be `-1` if no value was passed for
|
|
[`last_update_id`](#parameter-last_update_id) and no user
|
|
presence data was returned by the server. This can happen, for
|
|
example, if an organization has disabled presence.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 263).
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
Only present if `ping_only` is `false`.
|
|
|
|
The time when the server fetched the `presences` data included
|
|
in the response.
|
|
presences:
|
|
type: object
|
|
description: |
|
|
Only present if `ping_only` is `false`.
|
|
|
|
A dictionary where each entry describes the presence details
|
|
of a user in the Zulip organization. Entries can be in either
|
|
the modern presence format or the legacy presence format.
|
|
|
|
These entries will be the modern presence format when the
|
|
`last_updated_id` parameter is passed, or when the deprecated
|
|
`slim_presence` parameter is `true`.
|
|
|
|
If the deprecated `slim_presence` parameter is `false` and the
|
|
`last_updated_id` parameter is omitted, the entries will be in
|
|
the legacy presence API format.
|
|
|
|
**Note**: The legacy presence format should only be used when
|
|
interacting with old servers. It will be removed as soon as
|
|
doing so is practical.
|
|
additionalProperties:
|
|
description: |
|
|
Will be one of these two formats (modern or legacy) for user
|
|
presence data:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ModernPresenceFormat"
|
|
- type: object
|
|
description: |
|
|
`{user_email}`: Presence data (legacy format) for the user with
|
|
the specified Zulip API email.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/LegacyPresenceFormat"
|
|
zephyr_mirror_active:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Legacy property for a part of the Zephyr mirroring system.
|
|
|
|
**Deprecated**. Clients should ignore this field.
|
|
examples:
|
|
modern-presence-format-example:
|
|
description: |
|
|
Modern presence format:
|
|
value:
|
|
{
|
|
"msg": "",
|
|
"presences":
|
|
{
|
|
"10":
|
|
{
|
|
"idle_timestamp": 1656958530,
|
|
"active_timestamp": 1656958520,
|
|
},
|
|
},
|
|
"result": "success",
|
|
"server_timestamp": 1656958539.6287155,
|
|
"presence_last_update_id": 1000,
|
|
}
|
|
legacy-presence-format-example:
|
|
description: |
|
|
Legacy presence format:
|
|
value:
|
|
{
|
|
"msg": "",
|
|
"presences":
|
|
{
|
|
"user@example.com":
|
|
{
|
|
"aggregated":
|
|
{
|
|
"client": "website",
|
|
"status": "idle",
|
|
"timestamp": 1594825445,
|
|
},
|
|
"website":
|
|
{
|
|
"client": "website",
|
|
"status": "idle",
|
|
"timestamp": 1594825445,
|
|
"pushable": false,
|
|
},
|
|
},
|
|
},
|
|
"result": "success",
|
|
"server_timestamp": 1656958539.6287155,
|
|
"presence_last_update_id": 1000,
|
|
}
|
|
/users/me/status:
|
|
post:
|
|
operationId: update-status
|
|
summary: Update your status
|
|
tags: ["users"]
|
|
description: |
|
|
Change your [status](/help/status-and-availability).
|
|
|
|
A request to this endpoint will only change the parameters passed.
|
|
For example, passing just `status_text` requests a change in the status
|
|
text, but will leave the status emoji unchanged.
|
|
|
|
Clients that wish to set the user's status to a specific value should
|
|
pass all supported parameters.
|
|
|
|
**Changes**: In Zulip 5.0 (feature level 86), added support for
|
|
`emoji_name`, `emoji_code`, and `reaction_type` parameters.
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
The text content of the status message. Sending the empty string
|
|
will clear the user's status.
|
|
|
|
**Note**: The limit on the size of the message is 60 characters.
|
|
example: on vacation
|
|
away:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Whether the user should be marked as "away".
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
example: true
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
The name for the emoji to associate with this status.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: car
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: 1f697
|
|
reaction_type:
|
|
type: string
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: unicode_emoji
|
|
encoding:
|
|
away:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Client did not pass any new values.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when no changes were requested:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "status_text is too long (limit: 60 characters)",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the
|
|
`status_text` message exceeds the limit of
|
|
60 characters:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when `emoji_name` is not specified
|
|
but `emoji_code` or `reaction_type` is specified:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Emoji 'invalid' does not exist",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the emoji name does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid emoji name.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the emoji name is invalid:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid custom emoji.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the custom emoji is invalid:
|
|
/users/me/{stream_id}/topics:
|
|
get:
|
|
operationId: get-stream-topics
|
|
summary: Get topics in a channel
|
|
tags: ["channels"]
|
|
description: |
|
|
Get all topics the user has access to in a specific channel.
|
|
|
|
Note that for private channels with [protected
|
|
history](/help/channel-permissions), the user will only have access to
|
|
topics of messages sent after they [subscribed to](/api/subscribe) the
|
|
channel. Similarly, a user's [bot](/help/bots-overview#bot-type)
|
|
will only have access to messages sent after the bot was subscribed to
|
|
the channel, instead of when the user subscribed.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
topics:
|
|
type: array
|
|
description: |
|
|
An array of objects with information about user-accessible
|
|
topics in the specified channel, sorted by recency (i.e.,
|
|
the topic with the most recent message is ordered first).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
max_id:
|
|
description: |
|
|
The message ID of the last message sent to this topic.
|
|
type: integer
|
|
name:
|
|
description: |
|
|
The name of the topic.
|
|
type: string
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"topics":
|
|
[
|
|
{"max_id": 26, "name": "Denmark3"},
|
|
{"max_id": 23, "name": "Denmark1"},
|
|
{"max_id": 6, "name": "Denmark2"},
|
|
],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the user is attempting to fetch the topics
|
|
of a non-existing channel (or also a private channel they don't have access to):
|
|
/users/me/subscriptions:
|
|
get:
|
|
operationId: get-subscriptions
|
|
summary: Get subscribed channels
|
|
tags: ["channels"]
|
|
description: |
|
|
Get all channels that the user is subscribed to.
|
|
# operationId can be used to record which view function
|
|
# corresponds to an endpoint. TODO: Add these for more
|
|
# endpoints, and perhaps use this to provide links to implementations.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
description: |
|
|
You may pass the `include_subscribers` query parameter as follows:
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
parameters:
|
|
- $ref: "#/components/parameters/IncludeSubscribers"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
# TODO: Is this the best way to declare required elements in 200 responses?
|
|
- required:
|
|
- subscriptions
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary contains
|
|
information about one of the subscribed channels.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 8.0 (feature level 226).
|
|
|
|
Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscriptions":
|
|
[
|
|
{
|
|
"audible_notifications": true,
|
|
"color": "#e79ab5",
|
|
"creator_id": null,
|
|
"description": "A Scandinavian country",
|
|
"desktop_notifications": true,
|
|
"is_archived": false,
|
|
"is_muted": false,
|
|
"invite_only": false,
|
|
"name": "Denmark",
|
|
"pin_to_top": false,
|
|
"push_notifications": false,
|
|
"stream_id": 1,
|
|
"subscribers": [7, 10, 11, 12, 14],
|
|
},
|
|
{
|
|
"audible_notifications": true,
|
|
"color": "#e79ab5",
|
|
"creator_id": 8,
|
|
"description": "Located in the United Kingdom",
|
|
"desktop_notifications": true,
|
|
"is_archived": false,
|
|
"is_muted": false,
|
|
"invite_only": false,
|
|
"name": "Scotland",
|
|
"pin_to_top": false,
|
|
"push_notifications": false,
|
|
"stream_id": 3,
|
|
"subscribers": [7, 11, 12, 14],
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: subscribe
|
|
summary: Subscribe to a channel
|
|
tags: ["channels"]
|
|
description: |
|
|
Subscribe one or more users to one or more channels.
|
|
|
|
If any of the specified channels do not exist, they are automatically
|
|
created. The initial [channel settings](/api/update-stream) will be determined
|
|
by the optional parameters, like `invite_only`, detailed below.
|
|
|
|
Note that the ability to subscribe oneself and/or other users to a specified
|
|
channel depends on the [channel's privacy settings](/help/channel-permissions).
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 208), if a user
|
|
specified by the [`principals`][principals-param] parameter was
|
|
a deactivated user, or did not exist, then an HTTP status code
|
|
of 403 was returned with `code: "UNAUTHORIZED_PRINCIPAL"` in the
|
|
error response. As of this feature level, an HTTP status code of
|
|
400 is returned with `code: "BAD_REQUEST"` in the error response
|
|
for these cases.
|
|
|
|
[principals-param]: /api/subscribe#parameter-principals
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- type: include
|
|
description: |
|
|
To subscribe another user to a channel, you may pass in
|
|
the `principals` parameter, like so:
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- principals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
subscriptions:
|
|
description: |
|
|
A list of dictionaries containing the key `name` and value
|
|
specifying the name of the channel to subscribe. If the channel does not
|
|
exist a new channel is created. The description of the channel created can
|
|
be specified by setting the dictionary key `description` with an
|
|
appropriate value.
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the channel.
|
|
|
|
Clients should use the `max_stream_name_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum channel name length.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-channel-description)
|
|
to use for a new channel being created, in text/markdown format.
|
|
|
|
Clients should use the `max_stream_description_length` returned
|
|
by the [`POST /register`](/api/register-queue) endpoint to
|
|
determine the maximum channel description length.
|
|
required:
|
|
- name
|
|
example:
|
|
no-description:
|
|
value: {"name": "Verona"}
|
|
with-description:
|
|
value: {"name": "Verona", "description": "Italian city"}
|
|
example: [{"name": "Verona", "description": "Italian city"}]
|
|
principals:
|
|
$ref: "#/components/schemas/Principals"
|
|
authorization_errors_fatal:
|
|
description: |
|
|
A boolean specifying whether authorization errors (such as when the
|
|
requesting user is not authorized to access a private channel) should be
|
|
considered fatal or not. When `true`, an authorization error is reported
|
|
as such. When set to `false`, the response will be a 200 and any channels
|
|
where the request encountered an authorization error will be listed
|
|
in the `unauthorized` key.
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
announce:
|
|
description: |
|
|
If one of the channels specified did not exist previously and is thus created
|
|
by this call, this determines whether [notification bot](/help/configure-automated-notices)
|
|
will send an announcement about the new channel's creation.
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
invite_only:
|
|
description: |
|
|
As described above, this endpoint will create a new channel if passed
|
|
a channel name that doesn't already exist. This parameters and the ones
|
|
that follow are used to request an initial configuration of a created
|
|
channel; they are ignored for channels that already exist.
|
|
|
|
This parameter determines whether any newly created channels will be
|
|
private channels.
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
is_web_public:
|
|
description: |
|
|
This parameter determines whether any newly created channels will be
|
|
web-public channels.
|
|
|
|
Note that creating web-public channels requires the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
|
|
to be enabled on the Zulip server in question, the organization
|
|
to have enabled the `enable_spectator_access` realm setting, and
|
|
the current use to have permission under the organization's
|
|
`can_create_web_public_channel_group` realm setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 98).
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
is_default_stream:
|
|
description: |
|
|
This parameter determines whether any newly created channels will be
|
|
added as [default channels][default-channels] for new users joining
|
|
the organization.
|
|
|
|
[default-channels]: /help/set-default-channels-for-new-users
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status
|
|
could only be changed using the [dedicated API endpoint](/api/add-default-stream).
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
history_public_to_subscribers:
|
|
$ref: "#/components/schemas/HistoryPublicToSubscribers"
|
|
stream_post_policy:
|
|
$ref: "#/components/schemas/ChannelPostPolicy"
|
|
message_retention_days:
|
|
$ref: "#/components/schemas/MessageRetentionDays"
|
|
can_remove_subscribers_group:
|
|
$ref: "#/components/schemas/CanRemoveSubscribersGroup"
|
|
required:
|
|
- subscriptions
|
|
encoding:
|
|
subscriptions:
|
|
contentType: application/json
|
|
principals:
|
|
contentType: application/json
|
|
authorization_errors_fatal:
|
|
contentType: application/json
|
|
announce:
|
|
contentType: application/json
|
|
invite_only:
|
|
contentType: application/json
|
|
is_web_public:
|
|
contentType: application/json
|
|
is_default_stream:
|
|
contentType: application/json
|
|
history_public_to_subscribers:
|
|
contentType: application/json
|
|
stream_post_policy:
|
|
contentType: application/json
|
|
can_remove_subscribers_group:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the ID of the user and the value
|
|
is a list of the names of the channels that user was subscribed
|
|
to as a result of the request.
|
|
|
|
**Changes**: Before Zulip 10.0 (feature level 289), the user
|
|
keys were Zulip API email addresses, not user ID.
|
|
additionalProperties:
|
|
description: |
|
|
`{id}`: List of the names of the channels that were subscribed
|
|
to as a result of the query.
|
|
type: array
|
|
items:
|
|
type: string
|
|
already_subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the ID of the user and the value
|
|
is a list of the names of the channels that where the user was
|
|
not added as a subscriber in this request, because they were
|
|
already a subscriber.
|
|
|
|
**Changes**: Before Zulip 10.0 (feature level 289), the user
|
|
keys were Zulip API email addresses, not user IDs.
|
|
additionalProperties:
|
|
description: |
|
|
`{id}`: List of the names of the channels that the user is
|
|
already subscribed to.
|
|
type: array
|
|
items:
|
|
type: string
|
|
unauthorized:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of names of channels that the requesting user/bot was not
|
|
authorized to subscribe to. Only present if `"authorization_errors_fatal": false`.
|
|
example:
|
|
{
|
|
"already_subscribed": {"1": ["testing-help"]},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {"2": ["testing-help"]},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"msg": "Unable to access channel (private).",
|
|
"result": "error",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON response for when the requesting user does not have
|
|
access to a private channel and `"authorization_errors_fatal": true`:
|
|
patch:
|
|
operationId: update-subscriptions
|
|
summary: Update subscriptions
|
|
tags: ["channels"]
|
|
description: |
|
|
Update which channels you are subscribed to.
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
delete:
|
|
description: |
|
|
A list of channel names to unsubscribe from.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["Verona", "Denmark"]
|
|
add:
|
|
description: |
|
|
A list of objects describing which channels to subscribe to, optionally
|
|
including per-user subscription parameters (e.g. color) and if the
|
|
channel is to be created, its description.
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
color:
|
|
type: string
|
|
description:
|
|
type: string
|
|
example:
|
|
[
|
|
{"name": "Verona"},
|
|
{
|
|
"name": "Denmark",
|
|
"color": "#e79ab5",
|
|
"description": "A Scandinavian country",
|
|
},
|
|
]
|
|
encoding:
|
|
delete:
|
|
contentType: application/json
|
|
add:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- required:
|
|
- subscribed
|
|
- already_subscribed
|
|
- removed
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email
|
|
address of the user/bot and the value is a
|
|
list of the names of the channels that were
|
|
subscribed to as a result of the query.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_id}`: A list of the names of channels that
|
|
the user was subscribed to as a result of the query.
|
|
type: array
|
|
items:
|
|
type: string
|
|
already_subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email
|
|
address of the user/bot and the value is a
|
|
list of the names of the channels that the
|
|
user/bot is already subscribed to.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_id}`: A list of the names of channels that
|
|
the user was already subscribed to.
|
|
type: array
|
|
items:
|
|
type: string
|
|
not_removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of channels that the user
|
|
is already unsubscribed from, and hence
|
|
doesn't need to be unsubscribed.
|
|
removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of channels which were unsubscribed
|
|
from as a result of the query.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"subscribed": {},
|
|
"already_subscribed": {"iago@zulip.com": ["Verona"]},
|
|
"not_removed": [],
|
|
"removed": ["testing-help"],
|
|
"result": "success",
|
|
}
|
|
delete:
|
|
operationId: unsubscribe
|
|
summary: Unsubscribe from a channel
|
|
tags: ["channels"]
|
|
description: |
|
|
Unsubscribe yourself or other users from one or more channels.
|
|
|
|
In addition to managing the current user's subscriptions, this
|
|
endpoint can be used to remove other users from channels. This
|
|
is possible in 3 situations:
|
|
|
|
- Organization administrators can remove any user from any
|
|
channel.
|
|
- Users can remove a bot that they own from any channel that
|
|
the user [can access](/help/channel-permissions).
|
|
- Users can unsubscribe any user from a channel if they [have
|
|
access](/help/channel-permissions) to the channel and are a
|
|
member of the [user group](/api/get-user-groups) specified
|
|
by the [`can_remove_subscribers_group`][can-remove-parameter]
|
|
for the channel.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 208), if a user
|
|
specified by the [`principals`][principals-param] parameter was
|
|
a deactivated user, or did not exist, then an HTTP status code
|
|
of 403 was returned with `code: "UNAUTHORIZED_PRINCIPAL"` in the
|
|
error response. As of this feature level, an HTTP status code of
|
|
400 is returned with `code: "BAD_REQUEST"` in the error response
|
|
for these cases.
|
|
|
|
Before Zulip 8.0 (feature level 197),
|
|
the `can_remove_subscribers_group` setting
|
|
was named `can_remove_subscribers_group_id`.
|
|
|
|
Before Zulip 7.0 (feature level 161), the
|
|
`can_remove_subscribers_group_id` for all channels was always
|
|
the system group for organization administrators.
|
|
|
|
Before Zulip 6.0 (feature level 145), users had no special
|
|
privileges for managing bots that they own.
|
|
|
|
[principals-param]: /api/unsubscribe#parameter-principals
|
|
[can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
description: |
|
|
**Note**: Unsubscribing another user from a channel requires
|
|
administrative privileges.
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may specify the `principals` parameter like so:
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
subscriptions:
|
|
description: |
|
|
A list of channel names to unsubscribe from. This parameter is called
|
|
`streams` in our Python API.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["Verona", "Denmark"]
|
|
principals:
|
|
$ref: "#/components/schemas/Principals"
|
|
required:
|
|
- subscriptions
|
|
encoding:
|
|
subscriptions:
|
|
contentType: application/json
|
|
principals:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
not_removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of channels that the user is already unsubscribed
|
|
from, and hence doesn't need to be unsubscribed.
|
|
removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of channels which were unsubscribed from as a result
|
|
of the query.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"not_removed": [],
|
|
"removed": ["testing-help"],
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/NonExistingChannelNameError"
|
|
- description: |
|
|
A typical failed JSON response for when the target channel does not exist:
|
|
/users/me/subscriptions/muted_topics:
|
|
patch:
|
|
deprecated: true
|
|
operationId: mute-topic
|
|
summary: Topic muting
|
|
tags: ["channels"]
|
|
description: |
|
|
[Mute or unmute a topic](/help/mute-a-topic) within a channel that
|
|
the current user is subscribed to.
|
|
|
|
**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting
|
|
to newer servers should use the [POST /user_topics](/api/update-user-topic)
|
|
endpoint, as this endpoint may be removed in a future release.
|
|
|
|
Before Zulip 7.0 (feature level 169), this endpoint
|
|
returned an error if asked to mute a topic that was already muted
|
|
or asked to unmute a topic that had not previously been muted.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- stream_id
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the channel to access.
|
|
|
|
Clients must provide either `stream` or `stream_id` as a parameter
|
|
to this endpoint, but not both.
|
|
|
|
**Changes**: New in Zulip 2.0.0.
|
|
type: integer
|
|
example: 43
|
|
stream:
|
|
description: |
|
|
The name of the channel to access.
|
|
|
|
Clients must provide either `stream` or `stream_id` as a parameter
|
|
to this endpoint, but not both. Clients should use `stream_id`
|
|
instead of the `stream` parameter when possible.
|
|
type: string
|
|
example: Denmark
|
|
topic:
|
|
description: |
|
|
The topic to (un)mute. Note that the request will succeed regardless of
|
|
whether any messages have been sent to the specified topic.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
type: string
|
|
example: dinner
|
|
op:
|
|
description: |
|
|
Whether to mute (`add`) or unmute (`remove`) the provided topic.
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
required:
|
|
- topic
|
|
- op
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/mobile_push/test_notification:
|
|
post:
|
|
operationId: test-notify
|
|
summary: Send a test notification to mobile device(s)
|
|
tags: ["mobile"]
|
|
description: |
|
|
Trigger sending a test push notification to the user's
|
|
selected mobile device or all of their mobile devices.
|
|
|
|
**Changes**: Starting with Zulip 8.0 (feature level 234), test
|
|
notifications sent via this endpoint use `test` rather than
|
|
`test-by-device-token` in the `event` field. Also, as of this
|
|
feature level, all mobile push notifications now include a
|
|
`realm_name` field.
|
|
|
|
New in Zulip 8.0 (feature level 217).
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
The push token for the device to which to send the test notification.
|
|
|
|
If this parameter is not submitted, the test notification will be sent
|
|
to all of the user's devices registered on the server.
|
|
|
|
A mobile client should pass this parameter, to avoid triggering a test
|
|
notification for other clients.
|
|
type: string
|
|
example: "111222"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
"400":
|
|
description: |
|
|
Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InvalidPushDeviceTokenError"
|
|
- $ref: "#/components/schemas/InvalidRemotePushDeviceTokenError"
|
|
/user_topics:
|
|
post:
|
|
operationId: update-user-topic
|
|
summary: Update personal preferences for a topic
|
|
tags: ["channels"]
|
|
description: |
|
|
This endpoint is used to update the personal preferences for a topic,
|
|
such as the topic's visibility policy, which is used to implement
|
|
[mute a topic](/help/mute-a-topic) and related features.
|
|
|
|
This endpoint can be used to update the visibility policy for the single
|
|
channel and topic pair indicated by the parameters for a user.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 170). Previously,
|
|
toggling whether a topic was muted or unmuted was managed by the
|
|
[PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
stream_id:
|
|
description: |
|
|
The ID of the channel to access.
|
|
type: integer
|
|
example: 1
|
|
topic:
|
|
description: |
|
|
The topic for which the personal preferences needs to be updated.
|
|
Note that the request will succeed regardless of whether
|
|
any messages have been sent to the specified topic.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
type: string
|
|
example: dinner
|
|
visibility_policy:
|
|
description: |
|
|
Controls which visibility policy to set.
|
|
|
|
- 0 = None. Removes the visibility policy previously set for the topic.
|
|
- 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a channel.
|
|
- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted channel.
|
|
- 3 = Followed. [Follows the topic](/help/follow-a-topic).
|
|
|
|
In an unmuted channel, a topic visibility policy of unmuted will have the
|
|
same effect as the "None" visibility policy.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 219), added followed as
|
|
a visibility policy option.
|
|
type: integer
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
required:
|
|
- stream_id
|
|
- topic
|
|
- visibility_policy
|
|
encoding:
|
|
stream_id:
|
|
contentType: application/json
|
|
visibility_policy:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/users/me/muted_users/{muted_user_id}:
|
|
post:
|
|
operationId: mute-user
|
|
summary: Mute a user
|
|
tags: ["users"]
|
|
description: |
|
|
[Mute a user](/help/mute-a-user) from the perspective of the requesting
|
|
user. Messages sent by muted users will be automatically marked as read
|
|
and hidden for the user who muted them.
|
|
|
|
Muted users should be implemented by clients as follows:
|
|
|
|
- The server will immediately mark all messages sent by the muted
|
|
user as read. This will automatically clear any existing mobile
|
|
push notifications related to the muted user.
|
|
- The server will mark any new messages sent by the muted user as read
|
|
for the requesting user's account, which prevents all email and mobile
|
|
push notifications.
|
|
- Clients should exclude muted users from presence lists or other UI
|
|
for viewing or composing one-on-one direct messages. One-on-one direct
|
|
messages sent by muted users should be hidden everywhere in the Zulip UI.
|
|
- Channel messages and group direct messages sent by the muted
|
|
user should avoid displaying the content and name/avatar,
|
|
but should display that N messages by a muted user were
|
|
hidden (so that it is possible to interpret the messages by
|
|
other users who are talking with the muted user).
|
|
- Group direct message conversations including the muted user
|
|
should display muted users as "Muted user", rather than
|
|
showing their name, in lists of such conversations, along with using
|
|
a blank grey avatar where avatars are displayed.
|
|
- Administrative/settings UI elements for showing "All users that exist
|
|
on this channel or realm", e.g. for organization
|
|
administration or showing channel subscribers, should display
|
|
the user's name as normal.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MutedUserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Cannot mute self",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user ID is the current
|
|
user's ID:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "No such user",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is nonexistent or inaccessible:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User already muted",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is already muted:
|
|
delete:
|
|
operationId: unmute-user
|
|
summary: Unmute a user
|
|
tags: ["users"]
|
|
description: |
|
|
[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users)
|
|
from the perspective of the requesting user.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MutedUserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "No such user",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is nonexistent or inaccessible:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User is not muted",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is not previously muted:
|
|
/users/me/apns_device_token:
|
|
post:
|
|
operationId: add-apns-token
|
|
summary: Add an APNs device token
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint adds an APNs device token to register for iOS push notifications.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
The token provided by the device.
|
|
type: string
|
|
example: apple-tokenbb
|
|
appid:
|
|
description: |
|
|
The ID of the Zulip app that is making the request.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 223), this parameter was made
|
|
required. Previously, if it was unspecified, the server would use a default
|
|
value (based on the `ZULIP_IOS_APP_ID` server setting, which
|
|
defaulted to `"org.zulip.Zulip"`).
|
|
type: string
|
|
example: org.zulip.Zulip
|
|
required:
|
|
- token
|
|
- appid
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when the token's length is invalid
|
|
or it is empty:
|
|
example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Empty or invalid length token",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid APNS token",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the APNs token is invalid:
|
|
delete:
|
|
operationId: remove-apns-token
|
|
summary: Remove an APNs device token
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint removes an APNs device token for iOS push notifications.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
The token provided by the device.
|
|
type: string
|
|
example: apple-tokenbb
|
|
required:
|
|
- token
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when the token's length is invalid
|
|
or it is empty:
|
|
example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Empty or invalid length token",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Token does not exist",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the token does not exist:
|
|
/users/me/android_gcm_reg_id:
|
|
post:
|
|
operationId: add-fcm-token
|
|
summary: Add an FCM registration token
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint adds an FCM registration token for push notifications.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
The token provided by the device.
|
|
type: string
|
|
example: android-token
|
|
required:
|
|
- token
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when the token's length is invalid
|
|
or is empty:
|
|
example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Empty or invalid length token",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
delete:
|
|
operationId: remove-fcm-token
|
|
summary: Remove an FCM registration token
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint removes an FCM registration token for push notifications.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: |
|
|
The token provided by the device.
|
|
type: string
|
|
example: android-token
|
|
required:
|
|
- token
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when the token's length is invalid
|
|
or is empty:
|
|
example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Empty or invalid length token",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Token does not exist",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the token does not exist:
|
|
/users/{user_id}/subscriptions/{stream_id}:
|
|
get:
|
|
operationId: get-subscription-status
|
|
summary: Get subscription status
|
|
tags: ["channels"]
|
|
description: |
|
|
Check whether a user is subscribed to a channel.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 12).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
is_subscribed:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is subscribed to the channel.
|
|
example:
|
|
{"msg": "", "result": "success", "is_subscribed": false}
|
|
/realm/emoji/{emoji_name}:
|
|
post:
|
|
operationId: upload-custom-emoji
|
|
summary: Upload custom emoji
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
This endpoint is used to upload a custom emoji for use in the user's
|
|
organization. Access to this endpoint depends on the
|
|
[organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji).
|
|
x-parameter-description: |
|
|
As described above, the image file to upload must be provided in the
|
|
request's body.
|
|
|
|
## Maximum file size
|
|
|
|
The maximum file size for uploads can be configured by the
|
|
administrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB`
|
|
in the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults
|
|
to 5MB.
|
|
|
|
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
|
|
parameters:
|
|
- name: emoji_name
|
|
required: true
|
|
in: path
|
|
description: |
|
|
The name that should be associated with the uploaded emoji image/gif.
|
|
The emoji name can only contain letters, numbers, dashes, and spaces.
|
|
Upper and lower case letters are treated the same, and underscores (\_)
|
|
are treated the same as spaces (consistent with how the Zulip UI
|
|
handles emoji).
|
|
schema:
|
|
type: string
|
|
example: smile
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
filename:
|
|
type: string
|
|
format: binary
|
|
example: /path/to/img.png
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
delete:
|
|
operationId: deactivate-custom-emoji
|
|
summary: Deactivate custom emoji
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from
|
|
the user's organization.
|
|
|
|
Users can only deactivate custom emoji that they added themselves except for
|
|
organization administrators, who can deactivate any custom emoji.
|
|
|
|
Note that deactivated emoji will still be visible in old messages, reactions,
|
|
user statuses and channel descriptions.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an
|
|
HTTP status code of 400 when the emoji did not exist, instead of 404.
|
|
parameters:
|
|
- name: emoji_name
|
|
required: true
|
|
in: path
|
|
description: |
|
|
The name of the custom emoji to deactivate.
|
|
schema:
|
|
type: string
|
|
example: green_tick
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
An example JSON response for when no emoji exists with the provided name:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Emoji 'green_tick' does not exist",
|
|
}
|
|
/realm/emoji:
|
|
get:
|
|
operationId: get-custom-emoji
|
|
summary: Get all custom emoji
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get all the custom emoji in the user's organization.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
emoji:
|
|
type: object
|
|
description: |
|
|
An object that contains `emoji` objects, each identified with their
|
|
emoji ID as the key.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"emoji":
|
|
{
|
|
"1":
|
|
{
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/1/emoji/images/1.png",
|
|
"deactivated": false,
|
|
"author_id": 5,
|
|
},
|
|
},
|
|
}
|
|
/realm/presence:
|
|
get:
|
|
operationId: get-presence
|
|
summary: Get presence of all users
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get the presence information of all the users in an organization.
|
|
|
|
If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level
|
|
setting is set to `true`, presence information of only accessible
|
|
users are returned.
|
|
|
|
See [Zulip's developer documentation][subsystems-presence]
|
|
for details on the data model for presence in Zulip.
|
|
|
|
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
The time when the server fetched the `presences` data included
|
|
in the response.
|
|
presences:
|
|
type: object
|
|
description: |
|
|
A dictionary where each entry describes the presence details
|
|
of a user in the Zulip organization.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{user_email}`: Object containing the details of a user's presence.
|
|
The object's key is the user's Zulip API email.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/LegacyPresenceFormat"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"presences":
|
|
{
|
|
"iago@zulip.com":
|
|
{
|
|
"website":
|
|
{
|
|
"client": "website",
|
|
"pushable": false,
|
|
"status": "active",
|
|
"timestamp": 1656958485,
|
|
},
|
|
"aggregated":
|
|
{
|
|
"client": "website",
|
|
"status": "active",
|
|
"timestamp": 1656958485,
|
|
},
|
|
},
|
|
},
|
|
"result": "success",
|
|
"server_timestamp": 1656958539.6287155,
|
|
}
|
|
/realm/profile_fields:
|
|
get:
|
|
operationId: get-custom-profile-fields
|
|
summary: Get all custom profile fields
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get all the [custom profile fields](/help/custom-profile-fields)
|
|
configured for the user's organization.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
custom_fields:
|
|
type: array
|
|
description: |
|
|
An array containing all the custom profile fields defined in this
|
|
Zulip organization.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"custom_fields":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Phone number",
|
|
"type": 1,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 1,
|
|
"required": true,
|
|
"editable_by_user": false,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Biography",
|
|
"type": 2,
|
|
"hint": "What are you known for?",
|
|
"field_data": "",
|
|
"order": 2,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Favorite food",
|
|
"type": 1,
|
|
"hint": "Or drink, if you'd prefer",
|
|
"field_data": "",
|
|
"order": 3,
|
|
"required": false,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 4,
|
|
"name": "Favorite editor",
|
|
"type": 3,
|
|
"hint": "",
|
|
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
|
|
"order": 4,
|
|
"display_in_profile_summary": true,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 5,
|
|
"name": "Birthday",
|
|
"type": 4,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 5,
|
|
"required": false,
|
|
"editable_by_user": false,
|
|
},
|
|
{
|
|
"id": 6,
|
|
"name": "Favorite website",
|
|
"type": 5,
|
|
"hint": "Or your personal blog's URL",
|
|
"field_data": "",
|
|
"order": 6,
|
|
"display_in_profile_summary": true,
|
|
"required": false,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 7,
|
|
"name": "Mentor",
|
|
"type": 6,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 7,
|
|
"required": true,
|
|
"editable_by_user": false,
|
|
},
|
|
{
|
|
"id": 8,
|
|
"name": "GitHub",
|
|
"type": 7,
|
|
"hint": "Enter your GitHub username",
|
|
"field_data": '{"subtype":"github"}',
|
|
"order": 8,
|
|
"required": true,
|
|
"editable_by_user": true,
|
|
},
|
|
{
|
|
"id": 9,
|
|
"name": "Pronouns",
|
|
"type": 8,
|
|
"hint": "What pronouns should people use to refer to you?",
|
|
"order": 9,
|
|
"required": false,
|
|
"editable_by_user": true,
|
|
},
|
|
],
|
|
}
|
|
patch:
|
|
operationId: reorder-custom-profile-fields
|
|
summary: Reorder custom profile fields
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Reorder the custom profile fields in the user's organization.
|
|
|
|
Custom profile fields are displayed in Zulip UI widgets in order; this
|
|
endpoint allows administrative settings UI to change the field ordering.
|
|
|
|
This endpoint is used to implement the dragging feature described in the
|
|
[custom profile fields documentation](/help/custom-profile-fields).
|
|
x-requires-administrator: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
order:
|
|
description: |
|
|
A list of the IDs of all the custom profile fields defined in this
|
|
organization, in the desired new order.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
|
|
required:
|
|
- order
|
|
encoding:
|
|
order:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
post:
|
|
operationId: create-custom-profile-field
|
|
summary: Create a custom profile field
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.
|
|
x-requires-administrator: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: |
|
|
The name of the custom profile field, which will appear both in
|
|
user-facing settings UI for configuring custom profile fields and
|
|
in UI displaying a user's profile.
|
|
type: string
|
|
example: "Favorite programming language"
|
|
hint:
|
|
description: |
|
|
The help text to be displayed for the custom profile field in user-facing
|
|
settings UI for configuring custom profile fields.
|
|
type: string
|
|
example: "Your favorite programming language."
|
|
field_type:
|
|
description: |
|
|
The field type can be any of the supported custom profile field types. See the
|
|
[custom profile fields documentation](/help/custom-profile-fields)
|
|
for more details on what each type means.
|
|
|
|
- **1**: Short text
|
|
- **2**: Long text
|
|
- **3**: List of options
|
|
- **4**: Date picker
|
|
- **5**: Link
|
|
- **6**: Person picker
|
|
- **7**: External account
|
|
- **8**: Pronouns
|
|
|
|
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
|
|
type: integer
|
|
example: 3
|
|
field_data:
|
|
description: |
|
|
Field types 3 (List of options) and 7 (External account) support storing
|
|
additional configuration for the field type in the `field_data` attribute.
|
|
|
|
For field type 3 (List of options), this attribute is a JSON dictionary
|
|
defining the choices and the order they will be displayed in the
|
|
dropdown UI for individual users to select an option.
|
|
|
|
The interface for field type 7 is not yet stabilized.
|
|
type: object
|
|
example:
|
|
{
|
|
"python": {"text": "Python", "order": "1"},
|
|
"java": {"text": "Java", "order": "2"},
|
|
}
|
|
display_in_profile_summary:
|
|
description: |
|
|
Whether clients should display this profile field in a summary section of a
|
|
user's profile (or in a more easily accessible "small profile").
|
|
|
|
At most 2 profile fields may have this property be true in a given
|
|
organization. The "Long text" [profile field types][profile-field-types]
|
|
profile field types cannot be selected to be displayed in profile summaries.
|
|
|
|
The "Person picker" profile field is also not supported, but that is likely to
|
|
be temporary.
|
|
|
|
[profile-field-types]: /help/custom-profile-fields#profile-field-types
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 146).
|
|
type: boolean
|
|
example: true
|
|
required:
|
|
description: |
|
|
Whether an organization administrator has configured this profile field as
|
|
required.
|
|
|
|
Because the required property is mutable, clients cannot assume that a required
|
|
custom profile field has a value. The Zulip web application displays a prominent
|
|
banner to any user who has not set a value for a required field.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 244).
|
|
type: boolean
|
|
example: true
|
|
editable_by_user:
|
|
description: |
|
|
Whether regular users can edit this profile field on their own account.
|
|
|
|
Note that organization administrators can edit custom profile fields for any user
|
|
regardless of this setting.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 296).
|
|
type: boolean
|
|
example: true
|
|
required:
|
|
- field_type
|
|
encoding:
|
|
field_type:
|
|
contentType: application/json
|
|
field_data:
|
|
contentType: application/json
|
|
display_in_profile_summary:
|
|
contentType: application/json
|
|
required:
|
|
contentType: application/json
|
|
editable_by_user:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID for the custom profile field.
|
|
example: {"result": "success", "msg": "", "id": 9}
|
|
/realm/user_settings_defaults:
|
|
patch:
|
|
operationId: update-realm-user-settings-defaults
|
|
summary: Update realm-level defaults of user settings
|
|
tags: ["server_and_organizations"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Change the [default values of settings][new-user-defaults] for new users
|
|
joining the organization. Essentially all
|
|
[personal preference settings](/api/update-settings) are supported.
|
|
|
|
This feature can be invaluable for customizing Zulip's default
|
|
settings for notifications or UI to be appropriate for how the
|
|
organization is using Zulip. (Note that this only supports
|
|
personal preference settings, like when to send push
|
|
notifications or what emoji set to use, not profile or
|
|
identity settings that naturally should be different for each user).
|
|
|
|
Note that this endpoint cannot, at present, be used to modify
|
|
settings for existing users in any way.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 96). If any parameters
|
|
sent in the request are not supported by this endpoint, an
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array will
|
|
be returned in the JSON success response.
|
|
|
|
[new-user-defaults]: /help/configure-default-new-user-settings
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- left_side_userlist
|
|
- emojiset
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
dense_mode:
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
type: boolean
|
|
example: true
|
|
starred_message_counts:
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
type: boolean
|
|
example: true
|
|
receives_typing_notifications:
|
|
description: |
|
|
Whether the user is configured to receive typing notifications from other users.
|
|
The server will only deliver typing notifications events to users who for whom this
|
|
is enabled.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
|
|
only options to disable sending typing notifications.
|
|
type: boolean
|
|
example: true
|
|
fluid_layout_width:
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
type: boolean
|
|
example: true
|
|
high_contrast_mode:
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
type: boolean
|
|
example: true
|
|
web_mark_read_on_scroll_policy:
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
web_channel_default_view:
|
|
description: |
|
|
Web/desktop app setting controlling the default navigation
|
|
behavior when clicking on a channel link.
|
|
|
|
- 1 - Top topic in the channel
|
|
- 2 - Channel feed
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
|
|
was not configurable, and every user had the "Channel feed" behavior.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
example: 1
|
|
web_font_size_px:
|
|
description: |
|
|
User-configured primary `font-size` for the web application, in pixels.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
|
|
only adjustable via browser zoom. Note that this setting was not fully
|
|
implemented at this feature level.
|
|
type: integer
|
|
example: 14
|
|
web_line_height_percent:
|
|
description: |
|
|
User-configured primary `line-height` for the web application, in percent, so a
|
|
value of 120 represents a `line-height` of 1.2.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
|
|
not user-configurable. Note that this setting was not fully implemented at this
|
|
feature level.
|
|
type: integer
|
|
example: 122
|
|
color_scheme:
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
enable_drafts_synchronization:
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
type: boolean
|
|
example: true
|
|
translate_emoticons:
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
type: boolean
|
|
example: true
|
|
display_emoji_reaction_users:
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting users, rather than
|
|
a count, for messages with few total reactions. The ideal cutoff may depend on
|
|
the space available for displaying reactions; the official web application
|
|
displays names when 3 or fewer total reactions are present with this setting
|
|
enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
type: boolean
|
|
example: false
|
|
web_home_view:
|
|
description: |
|
|
The [home view](/help/configure-home-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "inbox" - Inbox view
|
|
- "all_messages" - Combined feed view
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
|
|
called `default_view`, which was new in Zulip 4.0 (feature level 42).
|
|
type: string
|
|
example: all_messages
|
|
web_escape_navigates_to_home_view:
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured home view](/help/configure-home-view).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called
|
|
`escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107).
|
|
type: boolean
|
|
example: true
|
|
left_side_userlist:
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
type: boolean
|
|
example: true
|
|
emojiset:
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
- "google-blob" - Google blobs
|
|
type: string
|
|
example: "google"
|
|
demote_inactive_streams:
|
|
description: |
|
|
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
user_list_style:
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
web_animate_image_previews:
|
|
description: |
|
|
Controls how animated images should be played in the message feed in the web/desktop application.
|
|
|
|
- "always" - Always play the animated images in the message feed.
|
|
- "on_hover" - Play the animated images on hover over them in the message feed.
|
|
- "never" - Never play animated images in the message feed.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images
|
|
always used to play in the message feed by default. This setting controls this
|
|
behaviour.
|
|
type: string
|
|
enum:
|
|
- always
|
|
- on_hover
|
|
- never
|
|
example: on_hover
|
|
web_stream_unreads_count_display_policy:
|
|
description: |
|
|
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
|
|
Channels that do not have an unread count will have a simple dot indicator for whether there are any
|
|
unread messages.
|
|
|
|
- 1 - All channels
|
|
- 2 - Unmuted channels and topics
|
|
- 3 - No channels
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 210).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 2
|
|
enable_stream_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for channel messages.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_email_notifications:
|
|
description: |
|
|
Enable email notifications for channel messages.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_push_notifications:
|
|
description: |
|
|
Enable mobile notifications for channel messages.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_audible_notifications:
|
|
description: |
|
|
Enable audible desktop notifications for channel messages.
|
|
type: boolean
|
|
example: true
|
|
notification_sound:
|
|
description: |
|
|
Notification sound name.
|
|
type: string
|
|
example: ding
|
|
enable_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for direct messages and @-mentions.
|
|
type: boolean
|
|
example: true
|
|
enable_sounds:
|
|
description: |
|
|
Enable audible desktop notifications for direct messages and
|
|
@-mentions.
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_email_notifications:
|
|
description: |
|
|
Enable email notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_push_notifications:
|
|
description: |
|
|
Enable push notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: false
|
|
enable_followed_topic_audible_notifications:
|
|
description: |
|
|
Enable audible desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: false
|
|
email_notifications_batching_period_seconds:
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
type: integer
|
|
example: 120
|
|
enable_offline_email_notifications:
|
|
description: |
|
|
Enable email notifications for direct messages and @-mentions received
|
|
when the user is offline.
|
|
type: boolean
|
|
example: true
|
|
enable_offline_push_notifications:
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is offline.
|
|
type: boolean
|
|
example: true
|
|
enable_online_push_notifications:
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is online.
|
|
type: boolean
|
|
example: true
|
|
enable_digest_emails:
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
type: boolean
|
|
example: true
|
|
message_content_in_email_notifications:
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
type: boolean
|
|
example: true
|
|
pm_content_in_desktop_notifications:
|
|
description: |
|
|
Include content of direct messages in desktop notifications.
|
|
type: boolean
|
|
example: true
|
|
wildcard_mentions_notify:
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
description: |
|
|
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
|
|
should send notifications like a personal mention.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
desktop_icon_count_display:
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unread messages
|
|
- 2 - DMs, mentions, and followed topics
|
|
- 3 - DMs and mentions
|
|
- 4 - None
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed
|
|
topics` option, renumbering the options to insert it in order.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
realm_name_in_email_notifications_policy:
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
automatically_follow_topics_policy:
|
|
description: |
|
|
Which [topics to follow automatically](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
description: |
|
|
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
automatically_follow_topics_where_mentioned:
|
|
description: |
|
|
Whether the server will automatically mark the user as following
|
|
topics where the user is mentioned.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 235).
|
|
type: boolean
|
|
example: true
|
|
presence_enabled:
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
type: boolean
|
|
example: true
|
|
enter_sends:
|
|
description: |
|
|
Whether pressing Enter in the compose box sends a message
|
|
(or saves a message edit).
|
|
type: boolean
|
|
example: true
|
|
twenty_four_hour_time:
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 99).
|
|
Previously, this default was edited using the
|
|
`default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint.
|
|
type: boolean
|
|
example: true
|
|
send_private_typing_notifications:
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
direct messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
send_stream_typing_notifications:
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
channel messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
send_read_receipts:
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
email_address_visibility:
|
|
description: |
|
|
The [policy][permission-level] for [which other users][help-email-visibility]
|
|
in this organization can see the user's real email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
- 5
|
|
example: 1
|
|
web_navigate_to_sent_message:
|
|
description: |
|
|
Web/desktop app setting for whether the user's view should
|
|
automatically go to the conversation where they sent a message.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
|
|
this behavior was not configurable.
|
|
type: boolean
|
|
example: true
|
|
encoding:
|
|
dense_mode:
|
|
contentType: application/json
|
|
starred_message_counts:
|
|
contentType: application/json
|
|
receives_typing_notifications:
|
|
contentType: application/json
|
|
fluid_layout_width:
|
|
contentType: application/json
|
|
high_contrast_mode:
|
|
contentType: application/json
|
|
web_mark_read_on_scroll_policy:
|
|
contentType: application/json
|
|
web_channel_default_view:
|
|
contentType: application/json
|
|
web_font_size_px:
|
|
contentType: application/json
|
|
web_line_height_percent:
|
|
contentType: application/json
|
|
color_scheme:
|
|
contentType: application/json
|
|
enable_drafts_synchronization:
|
|
contentType: application/json
|
|
translate_emoticons:
|
|
contentType: application/json
|
|
display_emoji_reaction_users:
|
|
contentType: application/json
|
|
web_escape_navigates_to_home_view:
|
|
contentType: application/json
|
|
left_side_userlist:
|
|
contentType: application/json
|
|
demote_inactive_streams:
|
|
contentType: application/json
|
|
user_list_style:
|
|
contentType: application/json
|
|
web_stream_unreads_count_display_policy:
|
|
contentType: application/json
|
|
enable_stream_desktop_notifications:
|
|
contentType: application/json
|
|
enable_stream_email_notifications:
|
|
contentType: application/json
|
|
enable_stream_push_notifications:
|
|
contentType: application/json
|
|
enable_stream_audible_notifications:
|
|
contentType: application/json
|
|
enable_desktop_notifications:
|
|
contentType: application/json
|
|
enable_sounds:
|
|
contentType: application/json
|
|
enable_followed_topic_desktop_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_email_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_push_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_audible_notifications:
|
|
contentType: application/json
|
|
email_notifications_batching_period_seconds:
|
|
contentType: application/json
|
|
enable_offline_email_notifications:
|
|
contentType: application/json
|
|
enable_offline_push_notifications:
|
|
contentType: application/json
|
|
enable_online_push_notifications:
|
|
contentType: application/json
|
|
enable_digest_emails:
|
|
contentType: application/json
|
|
message_content_in_email_notifications:
|
|
contentType: application/json
|
|
pm_content_in_desktop_notifications:
|
|
contentType: application/json
|
|
wildcard_mentions_notify:
|
|
contentType: application/json
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
contentType: application/json
|
|
desktop_icon_count_display:
|
|
contentType: application/json
|
|
realm_name_in_email_notifications_policy:
|
|
contentType: application/json
|
|
automatically_follow_topics_policy:
|
|
contentType: application/json
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
contentType: application/json
|
|
automatically_follow_topics_where_mentioned:
|
|
contentType: application/json
|
|
presence_enabled:
|
|
contentType: application/json
|
|
enter_sends:
|
|
contentType: application/json
|
|
twenty_four_hour_time:
|
|
contentType: application/json
|
|
send_private_typing_notifications:
|
|
contentType: application/json
|
|
send_stream_typing_notifications:
|
|
contentType: application/json
|
|
send_read_receipts:
|
|
contentType: application/json
|
|
email_address_visibility:
|
|
contentType: application/json
|
|
web_navigate_to_sent_message:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
|
|
/users/me/subscriptions/properties:
|
|
post:
|
|
operationId: update-subscription-settings
|
|
summary: Update subscription settings
|
|
tags: ["channels"]
|
|
description: |
|
|
This endpoint is used to update the user's personal settings for the
|
|
channels they are subscribed to, including muting, color, pinning, and
|
|
per-channel notification settings.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 111), response
|
|
object included the `subscription_data` in the
|
|
request. The endpoint now returns the more ergonomic
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array instead.
|
|
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
subscription_data:
|
|
description: |
|
|
A list of objects that describe the changes that should be applied in
|
|
each subscription. Each object represents a subscription, and must have
|
|
a `stream_id` key that identifies the channel, as well as the `property`
|
|
being modified and its new `value`.
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of a channel.
|
|
property:
|
|
type: string
|
|
enum:
|
|
- color
|
|
- is_muted
|
|
- in_home_view
|
|
- pin_to_top
|
|
- desktop_notifications
|
|
- audible_notifications
|
|
- push_notifications
|
|
- email_notifications
|
|
- wildcard_mentions_notify
|
|
description: |
|
|
One of the channel properties described below:
|
|
|
|
- `"color"`: The hex value of the user's display color for the channel.
|
|
|
|
- `"is_muted"`: Whether the channel is [muted](/help/mute-a-channel).<br>
|
|
**Changes**: As of Zulip 6.0 (feature level 139), updating either
|
|
`"is_muted"` or `"in_home_view"` generates two [subscription update
|
|
events](/api/get-events#subscription-update), one for each property,
|
|
that are sent to clients. Prior to this feature level, updating either
|
|
property only generated a subscription update event for
|
|
`"in_home_view"`. <br>
|
|
Prior to Zulip 2.1.0, this feature was represented
|
|
by the more confusingly named `"in_home_view"` (with the
|
|
opposite value: `in_home_view=!is_muted`); for
|
|
backwards-compatibility, modern Zulip still accepts that property.
|
|
|
|
- `"pin_to_top"`: Whether to pin the channel at the top of the channel list.
|
|
|
|
- `"desktop_notifications"`: Whether to show desktop notifications
|
|
for all messages sent to the channel.
|
|
|
|
- `"audible_notifications"`: Whether to play a sound
|
|
notification for all messages sent to the channel.
|
|
|
|
- `"push_notifications"`: Whether to trigger a mobile push
|
|
notification for all messages sent to the channel.
|
|
|
|
- `"email_notifications"`: Whether to trigger an email
|
|
notification for all messages sent to the channel.
|
|
|
|
- `"wildcard_mentions_notify"`: Whether wildcard mentions trigger
|
|
notifications as though they were personal mentions in this channel.
|
|
value:
|
|
oneOf:
|
|
- type: boolean
|
|
- type: string
|
|
description: |
|
|
The new value of the property being modified.
|
|
|
|
If the property is `"color"`, then `value` is a string
|
|
representing the hex value of the user's display
|
|
color for the channel. For all other above properties,
|
|
`value` is a boolean.
|
|
required:
|
|
- stream_id
|
|
- property
|
|
- value
|
|
example:
|
|
{"stream_id": 2, "property": "is_muted", "value": true}
|
|
example:
|
|
[
|
|
{"stream_id": 1, "property": "pin_to_top", "value": true},
|
|
{"stream_id": 3, "property": "color", "value": "#f00f00"},
|
|
]
|
|
required:
|
|
- subscription_data
|
|
encoding:
|
|
subscription_data:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
/users/{email}:
|
|
get:
|
|
operationId: get-user-by-email
|
|
summary: Get a user by email
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch details for a single user in the organization given a Zulip
|
|
API email address.
|
|
|
|
You can also fetch details on [all users in the organization](/api/get-users)
|
|
or [by user ID](/api/get-user).
|
|
|
|
Fetching by user ID is generally recommended when possible,
|
|
as a user might [change their email address](/help/change-your-email-address)
|
|
or change their [email address visibility](/help/configure-email-visibility),
|
|
either of which could change the client's ability to look them up by that
|
|
email address.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 302), the real email
|
|
address can be used in the `email` parameter and will fetch the target user's
|
|
data if and only if the target's email visibility setting permits the requester
|
|
to see the email address.
|
|
The dummy email addresses of the form `user{id}@{realm.host}` still work, and
|
|
will now work for **all** users, via identifying them by the embedded user ID.
|
|
|
|
New in Zulip Server 4.0 (feature level 39).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
|
|
parameters:
|
|
- name: email
|
|
in: path
|
|
description: |
|
|
The email address of the user to fetch. Two forms are supported:
|
|
|
|
- The real email address of the user (`delivery_email`). The lookup will
|
|
succeed if and only if the user exists and their email address visibility
|
|
setting permits the client to see the email address.
|
|
|
|
- The dummy Zulip API email address of the form `user{user_id}@{realm_host}`. This
|
|
is identical to simply [getting user by ID](/api/get-user). If the server or
|
|
realm change domains, the dummy email address used has to be adjustment to
|
|
match the new realm domain. This is legacy behavior for
|
|
backwards-compatibility, and will be removed in a future release.
|
|
|
|
**Changes**: Starting with Zulip 10.0 (feature level 302), lookups by real email
|
|
address match the semantics of the target's email visibility setting and dummy
|
|
email addresses work for all users, independently of their email visibility
|
|
setting.
|
|
|
|
Previously, lookups were done only using the Zulip API email addresses.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user":
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
}
|
|
patch:
|
|
operationId: update-user-by-email
|
|
summary: Update a user by email
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Administrative endpoint to update the details of another user in the organization by their email address.
|
|
Works the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their
|
|
real email address.
|
|
|
|
The requester needs to have permission to view the target user's real email address, subject to the
|
|
user's email address visibility setting. Otherwise, the dummy address of the format
|
|
`user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{email}`.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 313).
|
|
parameters:
|
|
- name: email
|
|
in: path
|
|
required: true
|
|
description: |
|
|
The email address of the user, specified following the same rules as
|
|
[`GET /users/{email}`](/api/get-user-by-email).
|
|
schema:
|
|
type: string
|
|
example: hamlet@zulip.com
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UpdateUser"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Guests cannot be organization administrators",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical unsuccessful JSON response:
|
|
/users/{user_id}:
|
|
get:
|
|
operationId: get-user
|
|
summary: Get a user
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch details for a single user in the organization.
|
|
|
|
You can also fetch details on [all users in the organization](/api/get-users)
|
|
or [by a user's Zulip API email](/api/get-user-by-email).
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user":
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
}
|
|
patch:
|
|
operationId: update-user
|
|
summary: Update a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Administrative endpoint to update the details of another user in the organization.
|
|
|
|
Supports everything an administrator can do to edit details of another
|
|
user's account, including editing full name,
|
|
[role](/help/roles-and-permissions), and [custom profile
|
|
fields](/help/custom-profile-fields).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UpdateUser"
|
|
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Guests cannot be organization administrators",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical unsuccessful JSON response:
|
|
|
|
delete:
|
|
operationId: deactivate-user
|
|
summary: Deactivate a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
[Deactivates a
|
|
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
|
|
given their user ID.
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
deactivation_notification_comment:
|
|
description: |
|
|
If not `null`, requests that the deactivated user receive
|
|
a notification email about their account deactivation.
|
|
|
|
If not `""`, encodes custom text written by the administrator
|
|
to be included in the notification email.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 135).
|
|
type: string
|
|
example: |
|
|
Farewell!
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Cannot deactivate the only organization owner",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response when attempting to deactivate the only
|
|
organization owner in an organization:
|
|
/realm/linkifiers:
|
|
get:
|
|
operationId: get-linkifiers
|
|
summary: Get linkifiers
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
List all of an organization's configured
|
|
[linkifiers](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 54). On older versions,
|
|
a similar `GET /realm/filters` endpoint was available with each entry in
|
|
a `[pattern, url_format, id]` tuple format.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
linkifiers:
|
|
type: array
|
|
description: |
|
|
An ordered array of objects, where each object
|
|
describes a linkifier.
|
|
|
|
Clients should always process linkifiers in the order given;
|
|
this is important if the realm has linkifiers with overlapping
|
|
patterns. The order can be modified using [`PATCH
|
|
/realm/linkifiers`](/api/reorder-linkifiers).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The string regex pattern which represents the pattern that
|
|
should be linkified by this linkifier.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
|
|
URL template to be used for linkifying matches.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"linkifiers":
|
|
[
|
|
{
|
|
"pattern": "#(?P<id>[0-9]+)",
|
|
"url_template": "https://github.com/zulip/zulip/issues/{id}",
|
|
"id": 1,
|
|
},
|
|
],
|
|
"result": "success",
|
|
}
|
|
patch:
|
|
operationId: reorder-linkifiers
|
|
summary: Reorder linkifiers
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Change the order that the regular expression patterns in the organization's
|
|
[linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics.
|
|
Useful when defining linkifiers with overlapping patterns.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 202). Before this feature level,
|
|
linkifiers were always processed in order by ID, which meant users would
|
|
need to delete and recreate them to reorder the list of linkifiers.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
ordered_linkifier_ids:
|
|
description: |
|
|
A list of the IDs of all the linkifiers defined in this
|
|
organization, in the desired new order.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [3, 2, 1, 5]
|
|
required:
|
|
- ordered_linkifier_ids
|
|
encoding:
|
|
ordered_linkifier_ids:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/realm/filters:
|
|
post:
|
|
operationId: add-linkifier
|
|
summary: Add a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Configure [linkifiers](/help/add-a-custom-linkifier),
|
|
regular expression patterns that are automatically linkified when they
|
|
appear in messages and topics.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pattern:
|
|
$ref: "#/components/schemas/LinkifierPattern"
|
|
url_template:
|
|
$ref: "#/components/schemas/LinkifierURLTemplate"
|
|
required:
|
|
- pattern
|
|
- url_template
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The numeric ID assigned to this filter.
|
|
example: {"id": 42, "result": "success", "msg": ""}
|
|
/realm/filters/{filter_id}:
|
|
delete:
|
|
operationId: remove-linkifier
|
|
summary: Remove a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Remove [linkifiers](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
parameters:
|
|
- name: filter_id
|
|
in: path
|
|
description: |
|
|
The ID of the linkifier that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
patch:
|
|
operationId: update-linkifier
|
|
summary: Update a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Update a [linkifier](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 57).
|
|
parameters:
|
|
- name: filter_id
|
|
in: path
|
|
description: |
|
|
The ID of the linkifier that you want to update.
|
|
schema:
|
|
type: integer
|
|
example: 5
|
|
required: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pattern:
|
|
$ref: "#/components/schemas/LinkifierPattern"
|
|
url_template:
|
|
$ref: "#/components/schemas/LinkifierURLTemplate"
|
|
required:
|
|
- pattern
|
|
- url_template
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/realm/playgrounds:
|
|
post:
|
|
operationId: add-code-playground
|
|
summary: Add a code playground
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was
|
|
fixed in Zulip 4.0 (feature level 57).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: |
|
|
The user-visible display name of the playground which can be
|
|
used to pick the target playground, especially when multiple
|
|
playground options exist for that programming language.
|
|
type: string
|
|
example: Python playground
|
|
pygments_language:
|
|
description: |
|
|
The name of the Pygments language lexer for that
|
|
programming language.
|
|
type: string
|
|
example: Python
|
|
url_template:
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
|
|
compliant URL template for the playground. The template should
|
|
contain exactly one variable named `code`, which determines how the
|
|
extracted code should be substituted in the playground URL.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 196). This replaced the
|
|
`url_prefix` parameter, which was used to construct URLs by just
|
|
concatenating `url_prefix` and `code`.
|
|
type: string
|
|
example: https://python.example.com?code={code}
|
|
required:
|
|
- name
|
|
- pygments_language
|
|
- url_template
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The numeric ID assigned to this playground.
|
|
example: {"id": 1, "result": "success", "msg": ""}
|
|
/realm/playgrounds/{playground_id}:
|
|
delete:
|
|
operationId: remove-code-playground
|
|
summary: Remove a code playground
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Remove a [code playground](/help/code-blocks#code-playgrounds) previously
|
|
configured for an organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
parameters:
|
|
- name: playground_id
|
|
in: path
|
|
description: |
|
|
The ID of the playground that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/export/realm:
|
|
get:
|
|
operationId: get-realm-exports
|
|
summary: Get all data exports
|
|
tags: ["server_and_organizations"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Fetch all the public and standard [data exports][export-data]
|
|
of the organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 304), only
|
|
public data exports could be fetched using this endpoint.
|
|
|
|
New in Zulip 2.1.
|
|
|
|
[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
exports:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details about a data export of the organization.
|
|
items:
|
|
$ref: "#/components/schemas/RealmExport"
|
|
example:
|
|
{
|
|
"exports":
|
|
[
|
|
{
|
|
"acting_user_id": 11,
|
|
"deleted_timestamp": null,
|
|
"export_type": 1,
|
|
"export_time": 1722243168.134179,
|
|
"export_url": "http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz",
|
|
"id": 323,
|
|
"failed_timestamp": null,
|
|
"pending": false,
|
|
},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
post:
|
|
operationId: export-realm
|
|
summary: Create a data export
|
|
tags: ["server_and_organizations"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Create a public or a standard [data export][export-data] of the organization.
|
|
|
|
!!! warn ""
|
|
|
|
**Note**: If you're the administrator of a self-hosted installation,
|
|
you may be looking for the documentation on [server data export and
|
|
import][data-export] or [server backups][backups].
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 304), only
|
|
public data exports could be created using this endpoint.
|
|
|
|
New in Zulip 2.1.
|
|
|
|
[export-data]: /help/export-your-organization#export-for-migrating-to-zulip-cloud-or-a-self-hosted-server
|
|
[data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export
|
|
[backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
export_type:
|
|
description: |
|
|
Whether to create a public or a standard data export.
|
|
|
|
- 1 = Public data export.
|
|
- 2 = Standard data export.
|
|
|
|
If not specified, defaults to 1.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 304). Previously,
|
|
all export requests were public data exports.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
default: 1
|
|
example: 2
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the data export created.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 182).
|
|
example: {"id": 1, "result": "success", "msg": ""}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Please request a manual export from zulip-admin@example.com.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the data export
|
|
exceeds the maximum allowed data export size.
|
|
/export/realm/consents:
|
|
get:
|
|
operationId: get-realm-export-consents
|
|
summary: Get data export consent state
|
|
tags: ["server_and_organizations"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data)
|
|
for their private data to be exported by organization administrators.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 295).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
export_consents:
|
|
type: array
|
|
description: |
|
|
An array of objects where each object contains a user ID and
|
|
whether the user has consented for their private data to be exported.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
user_id:
|
|
description: |
|
|
The user ID.
|
|
type: integer
|
|
consented:
|
|
description: |
|
|
Whether the user has consented for their private data export.
|
|
type: boolean
|
|
example:
|
|
{
|
|
"export_consents":
|
|
[
|
|
{"user_id": 11, "consented": true},
|
|
{"user_id": 6, "consented": false},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
/invites:
|
|
get:
|
|
operationId: get-invites
|
|
summary: Get all invitations
|
|
tags: ["invites"]
|
|
description: |
|
|
Fetch all unexpired [invitations](/help/invite-new-users) (i.e. email
|
|
invitations and reusable invitation links) that can be managed by the user.
|
|
|
|
Note that administrators can manage invitations that were created by other users.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 209), non-admin users could
|
|
only create email invitations, and therefore the response would never include
|
|
reusable invitation links for these users.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
invites:
|
|
type: array
|
|
description: |
|
|
An array of objects, each representing a single unexpired
|
|
[invitation](/help/invite-new-users).
|
|
items:
|
|
$ref: "#/components/schemas/Invite"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"invites":
|
|
[
|
|
{
|
|
email: "example@zulip.com",
|
|
expiry_date: null,
|
|
id: 1,
|
|
invited: 1710606654,
|
|
invited_as: 200,
|
|
invited_by_user_id: 9,
|
|
notify_referrer_on_join: true,
|
|
is_multiuse: false,
|
|
},
|
|
{
|
|
expiry_date: 1711463862,
|
|
id: 1,
|
|
invited: 1710599862,
|
|
invited_as: 400,
|
|
invited_by_user_id: 9,
|
|
is_multiuse: true,
|
|
notify_referrer_on_join: true,
|
|
link_url: "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/",
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: send-invites
|
|
summary: Send invitations
|
|
tags: ["invites"]
|
|
description: |
|
|
Send [invitations](/help/invite-new-users) to specified email addresses.
|
|
|
|
**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
|
|
parameter was removed and replaced by `invite_expires_in_minutes`.
|
|
|
|
In Zulip 5.0 (feature level 117), added support for passing `null` as
|
|
the `invite_expires_in_days` parameter to request an invitation that never
|
|
expires.
|
|
|
|
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
|
|
added which specified the number of days before the invitation would expire.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
invitee_emails:
|
|
description: |
|
|
The string containing the email addresses, separated by commas or
|
|
newlines, that will be sent an invitation.
|
|
type: string
|
|
example: example@zulip.com, logan@zulip.com
|
|
invite_expires_in_minutes:
|
|
$ref: "#/components/schemas/InviteExpirationParameter"
|
|
invite_as:
|
|
$ref: "#/components/schemas/InviteRoleParameter"
|
|
stream_ids:
|
|
description: |
|
|
A list containing the [IDs of the channels](/api/get-stream-id) that the
|
|
newly created user will be automatically subscribed to if the invitation
|
|
is accepted, in addition to any default channels that the new user may
|
|
be subscribed to based on the `include_realm_default_subscriptions`
|
|
parameter.
|
|
|
|
This list must be empty if the current user has the unlikely
|
|
configuration of being able to send invitations while lacking
|
|
permission to [subscribe other users to channels][can-subscribe-others].
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 180), specifying `stream_ids`
|
|
as an empty list resulted in an error.
|
|
|
|
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 10]
|
|
include_realm_default_subscriptions:
|
|
description: |
|
|
Boolean indicating whether the newly created user should be subscribed
|
|
to the [default channels][default-channels] for the organization.
|
|
|
|
Note that this parameter can be `true` even if the user creating the
|
|
invitation does not generally have permission to [subscribe other
|
|
users to channels][can-subscribe-others].
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
|
|
of Zulip behaved as though this parameter was always `false`; clients
|
|
needed to include the organization's default channels in the
|
|
`stream_ids` parameter for a newly created user to be automatically
|
|
subscribed to them.
|
|
|
|
[default-channels]: /help/set-default-channels-for-new-users
|
|
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
|
|
type: boolean
|
|
default: false
|
|
example: false
|
|
notify_referrer_on_join:
|
|
description: |
|
|
A boolean indicating whether the referrer would like to receive a
|
|
direct message from [notification
|
|
bot](/help/configure-automated-notices) when a user account is created
|
|
using this invitation.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 267). Previously,
|
|
referrers always received such direct messages.
|
|
type: boolean
|
|
example: false
|
|
default: true
|
|
required:
|
|
- invitee_emails
|
|
- stream_ids
|
|
encoding:
|
|
invite_expires_in_minutes:
|
|
contentType: application/json
|
|
stream_ids:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
example: {"msg": "", "result": "success"}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/InvitationFailedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!",
|
|
"errors":
|
|
[
|
|
[
|
|
"hamlet@zulip.com",
|
|
"Already has an account.",
|
|
false,
|
|
],
|
|
],
|
|
"sent_invitations": true,
|
|
"license_limit_reached": false,
|
|
"daily_limit_reached": false,
|
|
"code": "INVITATION_FAILED",
|
|
}
|
|
description: |
|
|
An example JSON error response for when some of the specified email addresses
|
|
have existing Zulip accounts.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Insufficient permission",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the user doesn't have permission
|
|
to send invitations.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You must specify at least one email address.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when no email address is specified.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid channel ID 11. No invites were sent.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when any of the specified channels
|
|
does not exist or the user does not have permission to access one of
|
|
the targeted channels.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You do not have permission to subscribe other users to channels.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the user doesn't have permission
|
|
to subscribe other users to channels and `stream_ids` is not empty.
|
|
/invites/multiuse:
|
|
post:
|
|
operationId: create-invite-link
|
|
summary: Create a reusable invitation link
|
|
tags: ["invites"]
|
|
description: |
|
|
Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
|
|
which can be used to invite new users to the organization.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin
|
|
users [with permission](/help/restrict-account-creation#change-who-can-send-invitations)
|
|
to use this endpoint. Previously, it was restricted to administrators only.
|
|
|
|
In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
|
|
parameter was removed and replaced by `invite_expires_in_minutes`.
|
|
|
|
In Zulip 5.0 (feature level 117), added support for passing `null` as
|
|
the `invite_expires_in_days` parameter to request an invitation that never
|
|
expires.
|
|
|
|
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
|
|
added which specified the number of days before the invitation would expire.
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
invite_expires_in_minutes:
|
|
$ref: "#/components/schemas/InviteExpirationParameter"
|
|
invite_as:
|
|
$ref: "#/components/schemas/InviteRoleParameter"
|
|
stream_ids:
|
|
description: |
|
|
A list containing the [IDs of the channels](/api/get-stream-id) that the
|
|
newly created user will be automatically subscribed to if the invitation
|
|
is accepted, in addition to any default channels that the new user may
|
|
be subscribed to based on the `include_realm_default_subscriptions`
|
|
parameter.
|
|
|
|
This list must be empty if the current user has the unlikely
|
|
configuration of being able to create reusable invitation links while
|
|
lacking permission to [subscribe other users to
|
|
channels][can-subscribe-others].
|
|
|
|
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
|
|
type: array
|
|
items:
|
|
type: integer
|
|
default: []
|
|
example: [1, 10]
|
|
include_realm_default_subscriptions:
|
|
description: |
|
|
Boolean indicating whether the newly created user should be subscribed
|
|
to the [default channels][default-channels] for the organization.
|
|
|
|
Note that this parameter can be `true` even if the current user does
|
|
not generally have permission to [subscribe other users to
|
|
channels][can-subscribe-others].
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
|
|
of Zulip behaved as though this parameter was always `false`; clients
|
|
needed to include the organization's default channels in the
|
|
`stream_ids` parameter for a newly created user to be automatically
|
|
subscribed to them.
|
|
|
|
[default-channels]: /help/set-default-channels-for-new-users
|
|
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
|
|
type: boolean
|
|
default: false
|
|
example: false
|
|
encoding:
|
|
invite_expires_in_minutes:
|
|
contentType: application/json
|
|
stream_ids:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
invite_link:
|
|
type: string
|
|
description: |
|
|
The URL of the [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
|
|
that was created by this request.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"invite_link": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Insufficient permission",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the user doesn't have permission
|
|
to send invitations.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid channel ID 11. No invites were sent.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when any of the specified channels
|
|
does not exist or the user does not have permission to access one of
|
|
the targeted channels.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You do not have permission to subscribe other users to channels.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the user doesn't have permission
|
|
to subscribe other users to channels and `stream_ids` is not empty.
|
|
/invites/{invite_id}:
|
|
delete:
|
|
operationId: revoke-email-invite
|
|
summary: Revoke an email invitation
|
|
tags: ["invites"]
|
|
description: |
|
|
Revoke an [email invitation](/help/invite-new-users#send-email-invitations).
|
|
|
|
A user can only revoke [invitations that they can
|
|
manage](/help/invite-new-users#manage-pending-invitations).
|
|
parameters:
|
|
- name: invite_id
|
|
in: path
|
|
description: |
|
|
The ID of the email invitation to be revoked.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "No such invitation",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for an invalid email invitation ID:
|
|
/invites/multiuse/{invite_id}:
|
|
delete:
|
|
operationId: revoke-invite-link
|
|
summary: Revoke a reusable invitation link
|
|
tags: ["invites"]
|
|
description: |
|
|
Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).
|
|
|
|
A user can only revoke [invitations that they can
|
|
manage](/help/invite-new-users#manage-pending-invitations).
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 209), only organization
|
|
administrators were able to create and revoke reusable invitation links.
|
|
parameters:
|
|
- name: invite_id
|
|
in: path
|
|
description: |
|
|
The ID of the reusable invitation link to be revoked.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "No such invitation",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for an invalid invitation link ID:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invitation has already been revoked",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the invitation link has already
|
|
been revoked:
|
|
/invites/{invite_id}/resend:
|
|
post:
|
|
operationId: resend-email-invite
|
|
summary: Resend an email invitation
|
|
tags: ["invites"]
|
|
description: |
|
|
Resend an [email invitation](/help/invite-new-users#send-email-invitations).
|
|
|
|
A user can only resend [invitations that they can
|
|
manage](/help/invite-new-users#manage-pending-invitations).
|
|
parameters:
|
|
- name: invite_id
|
|
in: path
|
|
description: |
|
|
The ID of the email invitation to be resent.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "No such invitation",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for an invalid email invitation ID:
|
|
/register:
|
|
post:
|
|
operationId: register-queue
|
|
summary: Register an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
This powerful endpoint can be used to register a Zulip "event queue"
|
|
(subscribed to certain types of "events", or updates to the messages
|
|
and other Zulip data the current user has access to), as well as to
|
|
fetch the current state of that data.
|
|
|
|
(`register` also powers the `call_on_each_event` Python API, and is
|
|
intended primarily for complex applications for which the more convenient
|
|
`call_on_each_event` API is insufficient).
|
|
|
|
This endpoint returns a `queue_id` and a `last_event_id`; these can be
|
|
used in subsequent calls to the
|
|
["events" endpoint](/api/get-events) to request events from
|
|
the Zulip server using long-polling.
|
|
|
|
The server will queue events for up to 10 minutes of inactivity.
|
|
After 10 minutes, your event queue will be garbage-collected. The
|
|
server will send `heartbeat` events every minute, which makes it easy
|
|
to implement a robust client that does not miss events unless the
|
|
client loses network connectivity with the Zulip server for 10 minutes
|
|
or longer.
|
|
|
|
Once the server garbage-collects your event queue, the server will
|
|
[return an error](/api/get-events#bad_event_queue_id-errors)
|
|
with a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from
|
|
the event queue. Your software will need to handle that error
|
|
condition by re-initializing itself (e.g. this is what triggers your
|
|
browser reloading the Zulip web app when your laptop comes back online
|
|
after being offline for more than 10 minutes).
|
|
|
|
When prototyping with this API, we recommend first calling `register`
|
|
with no `event_types` parameter to see all the available data from all
|
|
supported event types. Before using your client in production, you
|
|
should set appropriate `event_types` and `fetch_event_types` filters
|
|
so that your client only requests the data it needs. A few minutes
|
|
doing this often saves 90% of the total bandwidth and other resources
|
|
consumed by a client using this API.
|
|
|
|
See the [events system developer documentation][events-system-docs]
|
|
if you need deeper details about how the Zulip event queue system
|
|
works, avoids clients needing to worry about large classes of
|
|
potentially messy races, etc.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 183), the
|
|
`realm_community_topic_editing_limit_seconds` property
|
|
was returned by the response. It was removed because it
|
|
had not been in use since the realm setting
|
|
`move_messages_within_stream_limit_seconds` was introduced
|
|
in feature level 162.
|
|
|
|
In Zulip 7.0 (feature level 163), the realm setting
|
|
`email_address_visibility` was removed. It was replaced by a [user
|
|
setting](/api/update-settings#parameter-email_address_visibility) with
|
|
a [realm user default][user-defaults], with the encoding of different
|
|
values preserved. Clients can support all versions by supporting the
|
|
current API and treating every user as having the realm's
|
|
`email_address_visibility` value.
|
|
|
|
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
|
|
[events-system-docs]: https://zulip.readthedocs.io/en/latest/subsystems/events-system.html
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- event_types
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
apply_markdown:
|
|
description: |
|
|
Set to `true` if you would like the content to be rendered in HTML
|
|
format (otherwise the API will return the raw text that the user
|
|
entered)
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
client_gravatar:
|
|
description: |
|
|
Whether the client supports computing gravatars URLs. If
|
|
enabled, `avatar_url` will be included in the response only
|
|
if there is a Zulip avatar, and will be `null` for users who
|
|
are using gravatar as their avatar. This option
|
|
significantly reduces the compressed size of user data,
|
|
since gravatar URLs are long, random strings and thus do not
|
|
compress well. The `client_gravatar` field is set to `true` if
|
|
clients can compute their own gravatars.
|
|
|
|
The default value is `true` for authenticated requests and
|
|
`false` for [unauthenticated
|
|
requests](/help/public-access-option). Passing `true` in
|
|
an unauthenticated request is an error.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 149), this
|
|
parameter was silently ignored and processed as though it
|
|
were `false` in unauthenticated requests.
|
|
type: boolean
|
|
example: false
|
|
include_subscribers:
|
|
description: |
|
|
Whether each returned channel object should include a `subscribers`
|
|
field containing a list of the user IDs of its subscribers.
|
|
|
|
(This may be significantly slower in organizations with
|
|
thousands of users subscribed to many channels.)
|
|
|
|
Passing `true` in an [unauthenticated
|
|
request](/help/public-access-option) is an error.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 149), this
|
|
parameter was silently ignored and processed as though it
|
|
were `false` in unauthenticated requests.
|
|
|
|
New in Zulip 2.1.0.
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
slim_presence:
|
|
description: |
|
|
If `true`, the `presences` object returned in the response will be keyed
|
|
by user ID and the entry for each user's presence data will be in the
|
|
modern format.
|
|
|
|
**Changes**: New in Zulip 3.0 (no feature level; API unstable).
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
presence_history_limit_days:
|
|
description: |
|
|
Limits how far back in time to fetch user presence data. If not specified,
|
|
defaults to 14 days. A value of N means that the oldest presence data
|
|
fetched will be from at most N days ago.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 288).
|
|
type: integer
|
|
example: 365
|
|
event_types:
|
|
$ref: "#/components/schemas/Event_types"
|
|
all_public_streams:
|
|
$ref: "#/components/schemas/AllPublicChannels"
|
|
client_capabilities:
|
|
description: |
|
|
Dictionary containing details on features the client supports that are
|
|
relevant to the format of responses sent by the server.
|
|
|
|
- `notification_settings_null`: Boolean for whether the
|
|
client can handle the current API with `null` values for
|
|
channel-level notification settings (which means the channel
|
|
is not customized and should inherit the user's global
|
|
notification settings for channel messages).
|
|
<br />
|
|
**Changes**: New in Zulip 2.1.0. In earlier Zulip releases,
|
|
channel-level notification settings were simple booleans.
|
|
|
|
- `bulk_message_deletion`: Boolean for whether the client's
|
|
handler for the `delete_message` event type has been
|
|
updated to process the new bulk format (with a
|
|
`message_ids`, rather than a singleton `message_id`).
|
|
Otherwise, the server will send `delete_message` events
|
|
in a loop.
|
|
<br />
|
|
**Changes**: New in Zulip 3.0 (feature level 13). This
|
|
capability is for backwards-compatibility; it will be
|
|
required in a future server release.
|
|
|
|
- `user_avatar_url_field_optional`: Boolean for whether the
|
|
client required avatar URLs for all users, or supports
|
|
using `GET /avatar/{user_id}` to access user avatars. If the
|
|
client has this capability, the server may skip sending a
|
|
`avatar_url` field in the `realm_user` at its sole discretion
|
|
to optimize network performance. This is an important optimization
|
|
in organizations with 10,000s of users.
|
|
<br />
|
|
**Changes**: New in Zulip 3.0 (feature level 18).
|
|
|
|
- `stream_typing_notifications`: Boolean for whether the client
|
|
supports channel typing notifications.
|
|
<br />
|
|
**Changes**: New in Zulip 4.0 (feature level 58). This capability is
|
|
for backwards-compatibility; it will be required in a
|
|
future server release.
|
|
|
|
- `user_settings_object`: Boolean for whether the client supports the modern
|
|
`user_settings` event type. If false, the server will additionally send the
|
|
legacy `update_global_notifications` and `update_display_settings` event
|
|
types.
|
|
<br />
|
|
**Changes**: New in Zulip 5.0 (feature level 89). This capability is for
|
|
backwards-compatibility; it will be removed in a future server release.
|
|
Because the feature level 89 API changes were merged together, clients can
|
|
safely make a request with this client capability and also request all three
|
|
event types (`user_settings`, `update_display_settings`,
|
|
`update_global_notifications`), and get exactly one copy of settings data on
|
|
any server version. Clients can then use the `zulip_feature_level` in the
|
|
`/register` response or the presence/absence of a `user_settings` key to
|
|
determine where to look for the data.
|
|
|
|
- `linkifier_url_template`: Boolean for whether the client accepts
|
|
[linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant
|
|
URL templates for linkifying matches. If false or unset, then the
|
|
`realm_linkifiers` array in the `/register` response will be empty
|
|
if present, and no `realm_linkifiers` [events][events-linkifiers]
|
|
will be sent to the client.
|
|
<br />
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This capability
|
|
is for backwards-compatibility.
|
|
|
|
- `user_list_incomplete`: Boolean for whether the client supports not having an
|
|
incomplete user database. If true, then the `realm_users` array in the `register`
|
|
response will not include data for inaccessible users and clients of guest users will
|
|
not receive `realm_user op:add` events for newly created users that are not accessible
|
|
to the current user.
|
|
<br />
|
|
**Changes**: New in Zulip 8.0 (feature level 232). This
|
|
capability is for backwards-compatibility.
|
|
|
|
- `include_deactivated_groups`: Boolean for whether the client can handle
|
|
deactivated user groups by themselves. If false, then the `realm_user_groups`
|
|
array in the `/register` response will only include active groups, clients
|
|
will receive a `remove` event instead of `update` event when a group is
|
|
deactivated and no `update` event will be sent to the client if a deactivated
|
|
user group is renamed.
|
|
<br />
|
|
**Changes**: New in Zulip 10.0 (feature level 294). This
|
|
capability is for backwards-compatibility.
|
|
|
|
- `archived_channels`: Boolean for whether the client supports processing
|
|
[archived channels](/help/archive-a-channel) in the `stream` and
|
|
`subscription` event types. If `false`, the server will not include data
|
|
related to archived channels in the `register` response or in events.
|
|
<br />
|
|
**Changes**: New in Zulip 10.0 (feature level 315). This allows clients to
|
|
access archived channels, without breaking backwards-compatibility for
|
|
existing clients.
|
|
|
|
[help-linkifiers]: /help/add-a-custom-linkifier
|
|
[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html
|
|
[events-linkifiers]: /api/get-events#realm_linkifiers
|
|
type: object
|
|
example: {"notification_settings_null": true}
|
|
fetch_event_types:
|
|
description: |
|
|
Same as the `event_types` parameter except that the values in
|
|
`fetch_event_types` are used to fetch initial data. If
|
|
`fetch_event_types` is not provided, `event_types` is used and if
|
|
`event_types` is not provided, this parameter defaults to `null`.
|
|
|
|
Event types not supported by the server are ignored, in order to simplify
|
|
the implementation of client apps that support multiple server versions.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["message"]
|
|
narrow:
|
|
$ref: "#/components/schemas/Narrow"
|
|
encoding:
|
|
apply_markdown:
|
|
contentType: application/json
|
|
client_gravatar:
|
|
contentType: application/json
|
|
include_subscribers:
|
|
contentType: application/json
|
|
slim_presence:
|
|
contentType: application/json
|
|
event_types:
|
|
contentType: application/json
|
|
all_public_streams:
|
|
contentType: application/json
|
|
client_capabilities:
|
|
contentType: application/json
|
|
fetch_event_types:
|
|
contentType: application/json
|
|
narrow:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
queue_id:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The ID of the queue that has been allocated for your client.
|
|
|
|
Will be `null` only for unauthenticated access in realms that have
|
|
enabled the [public access option](/help/public-access-option).
|
|
last_event_id:
|
|
type: integer
|
|
description: |
|
|
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
The server's current [Zulip feature level](/api/changelog).
|
|
|
|
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
|
|
in the endpoint's response. Previously, it was only present if
|
|
`event_types` included `zulip_version`.
|
|
|
|
New in Zulip 3.0 (feature level 1).
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The server's version number. This is often a release version number,
|
|
like `2.1.7`. But for a server running a [version from Git][git-release],
|
|
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
|
|
|
|
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
|
|
in the endpoint's response. Previously, it was only present if
|
|
`event_types` included `zulip_version`.
|
|
|
|
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The `git merge-base` between `zulip_version` and official branches
|
|
in the public
|
|
[Zulip server and web app repository](https://github.com/zulip/zulip),
|
|
in the same format as `zulip_version`. This will equal
|
|
`zulip_version` if the server is not running a fork of the Zulip server.
|
|
|
|
This will be `""` if the server does not know its `merge-base`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
Present if `alert_words` is present in `fetch_event_types`.
|
|
|
|
An array of strings, each an [alert word](/help/dm-mention-alert-notifications#alert-words)
|
|
that the current user has configured.
|
|
items:
|
|
type: string
|
|
custom_profile_fields:
|
|
type: array
|
|
description: |
|
|
Present if `custom_profile_fields` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains the
|
|
details of a single custom profile field that is available to users
|
|
in this Zulip organization. This must be combined with the custom profile
|
|
field values on individual user objects to display users' profiles.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
custom_profile_field_types:
|
|
type: object
|
|
description: |
|
|
Present if `custom_profile_fields` is present in `fetch_event_types`.
|
|
|
|
An array of objects; each object describes a type of custom profile field
|
|
that could be configured on this Zulip server. Each custom profile type
|
|
has an ID and the `type` property of a custom profile field is equal
|
|
to one of these IDs.
|
|
|
|
This attribute is only useful for clients containing UI for changing
|
|
the set of configured custom profile fields in a Zulip organization.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{FIELD_TYPE}`: Dictionary which contains the details
|
|
of the field type with the field type as the name of the
|
|
property itself. The current supported field types are as follows:
|
|
|
|
- `SHORT_TEXT`
|
|
- `LONG_TEXT`
|
|
- `DATE` for date-based fields.
|
|
- `SELECT` for a list of options.
|
|
- `URL` for links.
|
|
- `EXTERNAL_ACCOUNT` for external accounts.
|
|
- `USER` for selecting a user for the field.
|
|
- `PRONOUNS` for a short text field with convenient typeahead for one's preferred pronouns.
|
|
|
|
**Changes**: `PRONOUNS` type added in Zulip 6.0 (feature level 151).
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field type.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the custom profile field type.
|
|
realm_date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp (UTC) for when the organization was
|
|
created.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 203).
|
|
demo_organization_scheduled_deletion_date:
|
|
type: integer
|
|
description: |
|
|
Present if the realm is a demo organization.
|
|
|
|
The UNIX timestamp (UTC) when the demo organization will be
|
|
automatically deleted. Clients should use this to display a
|
|
prominent warning to the user that the organization will be
|
|
deleted at the indicated time.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 94).
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
An array containing draft objects for the user. These drafts are being
|
|
stored on the backend for the purpose of syncing across devices. This
|
|
array will be empty if `enable_drafts_synchronization` is set to `false`.
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
onboarding_steps:
|
|
type: array
|
|
description: |
|
|
Present if `onboarding_steps` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries, where each dictionary contains details about
|
|
a single onboarding step that should be shown to the user.
|
|
|
|
We expect that only official Zulip clients will interact with this data.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
|
|
`hotspots`. Prior to this feature level, one-time notice onboarding
|
|
steps were not supported, and the `type` field in these objects did not
|
|
exist as all onboarding steps were implicitly hotspots.
|
|
items:
|
|
$ref: "#/components/schemas/OnboardingStep"
|
|
max_message_id:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
Present if `message` is present in `fetch_event_types`.
|
|
|
|
The highest message ID among all messages the user has received as of the
|
|
moment of this request.
|
|
|
|
**Deprecated**: This field may be removed in future versions as it no
|
|
longer has a clear purpose. Clients wishing to fetch the latest messages
|
|
should pass `"anchor": "latest"` to `GET /messages`.
|
|
max_stream_name_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a channel name, in Unicode code
|
|
points. Clients should use this property rather than hardcoding
|
|
field sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this required `stream` in `fetch_event_types`, was called
|
|
`stream_name_max_length`, and always had a value of 60.
|
|
max_stream_description_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a channel description, in Unicode
|
|
code points. Clients should use this property rather than hardcoding
|
|
field sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this required `stream` in `fetch_event_types`, was called
|
|
`stream_description_max_length`, and always had a value of 1024.
|
|
max_topic_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a topic, in Unicode code points.
|
|
Clients should use this property rather than hardcoding field
|
|
sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this property always had a value of 60.
|
|
max_message_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a message, in Unicode code points.
|
|
Clients should use this property rather than hardcoding field
|
|
sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this property always had a value of 10000.
|
|
server_presence_ping_interval_seconds:
|
|
type: integer
|
|
description: |
|
|
For clients implementing the [presence](/api/get-presence) system,
|
|
the time interval the client should use for sending presence requests
|
|
to the server (and thus receive presence updates from the server).
|
|
|
|
It is important for presence implementations to use both this and
|
|
`server_presence_offline_threshold_seconds` correctly, so that a Zulip
|
|
server can change these values to manage the trade-off between load and
|
|
freshness of presence data.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 60
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip mobile apps prior to this parameter being introduced.
|
|
server_presence_offline_threshold_seconds:
|
|
type: integer
|
|
description: |
|
|
How old a presence timestamp for a given user can be before the user
|
|
should be displayed as offline by clients displaying Zulip presence
|
|
data. See the related `server_presence_ping_interval_seconds` for details.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 140
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip client apps prior to this parameter being introduced.
|
|
server_typing_started_expiry_period_milliseconds:
|
|
type: integer
|
|
description: |
|
|
For clients implementing [typing notifications](/api/set-typing-status)
|
|
protocol, the time interval in milliseconds that the client should wait
|
|
for additional [typing start](/api/get-events#typing-start) events from
|
|
the server before removing an active typing indicator.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 15000
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip apps prior to this parameter being introduced.
|
|
server_typing_stopped_wait_period_milliseconds:
|
|
type: integer
|
|
description: |
|
|
For clients implementing [typing notifications](/api/set-typing-status)
|
|
protocol, the time interval in milliseconds that the client should wait
|
|
when a user stops interacting with the compose UI before sending a stop
|
|
notification to the server.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 5000
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip apps prior to this parameter being introduced.
|
|
server_typing_started_wait_period_milliseconds:
|
|
type: integer
|
|
description: |
|
|
For clients implementing [typing notifications](/api/set-typing-status)
|
|
protocol, the time interval in milliseconds that the client should use
|
|
to send regular start notifications to the server to indicate that the
|
|
user is still actively interacting with the compose UI.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 10000
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip apps prior to this parameter being introduced.
|
|
scheduled_messages:
|
|
type: array
|
|
description: |
|
|
Present if `scheduled_messages` is present in `fetch_event_types`.
|
|
|
|
An array of all undelivered scheduled messages by the user.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 179).
|
|
items:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
muted_topics:
|
|
type: array
|
|
deprecated: true
|
|
description: |
|
|
Present if `muted_topics` is present in `fetch_event_types`.
|
|
|
|
Array of tuples, where each tuple describes a muted topic.
|
|
The first element of the tuple is the channel name in which the topic
|
|
has to be muted, the second element is the topic name to be muted
|
|
and the third element is an integer UNIX timestamp representing
|
|
when the topic was muted.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting
|
|
with this version, `muted_topics` will only be present in the
|
|
response if the `user_topic` object, which generalizes and replaces
|
|
this field, is not explicitly requested via `fetch_event_types`.
|
|
|
|
Before Zulip 3.0 (feature level 1), the `muted_topics`
|
|
array objects were 2-item tuples and did not include the timestamp
|
|
information for when the topic was muted.
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
muted_users:
|
|
type: array
|
|
description: |
|
|
Present if `muted_users` is present in `fetch_event_types`.
|
|
|
|
A list of dictionaries where each dictionary describes
|
|
a [muted user](/api/mute-user).
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and timestamp of a muted user.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the muted user.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user was muted.
|
|
presences:
|
|
type: object
|
|
description: |
|
|
Present if `presence` is present in `fetch_event_types`.
|
|
|
|
A dictionary where each entry describes the presence details of a
|
|
user in the Zulip organization.
|
|
|
|
The format of the entry (modern or legacy) depends on the value of
|
|
[`slim_presence`](#parameter-slim_presence).
|
|
|
|
Users who have been offline for multiple weeks may not appear in this object.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
Will be one of these two formats (modern or legacy) for user
|
|
presence data:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ModernPresenceFormat"
|
|
- type: object
|
|
description: |
|
|
`{user_email}`: Presence data (legacy format) for the user with
|
|
the specified Zulip API email.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/LegacyPresenceFormat"
|
|
presence_last_update_id:
|
|
type: integer
|
|
description: |
|
|
Present if `presence` is present in `fetch_event_types`.
|
|
|
|
Provides the `last_update_id` value of the latest presence data fetched by
|
|
the server and included in the response in `presences`. This can be used
|
|
as the value of the `presence_last_update_id` parameter when polling
|
|
for presence data at the [/users/me/presence](/api/update-presence) endpoint
|
|
to tell the server to only fetch the relevant newer data in order to skip
|
|
redundant already-known presence information.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 263).
|
|
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
Present if `presence` is present in `fetch_event_types`.
|
|
|
|
The time when the server fetched the
|
|
`presences` data included in the response.
|
|
Matches the similar field in presence
|
|
responses.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 70).
|
|
realm_domains:
|
|
type: array
|
|
description: |
|
|
Present if `realm_domains` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a domain within
|
|
which users can join the organization without and invitation.
|
|
items:
|
|
$ref: "#/components/schemas/RealmDomain"
|
|
realm_emoji:
|
|
description: |
|
|
Present if `realm_emoji` is present in `fetch_event_types`.
|
|
|
|
A dictionary of objects where each object describes a custom
|
|
emoji that has been uploaded in this Zulip organization.
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
realm_linkifiers:
|
|
type: array
|
|
description: |
|
|
Present if `realm_linkifiers` is present in `fetch_event_types`.
|
|
|
|
An ordered array of objects where each object describes a single
|
|
[linkifier](/help/add-a-custom-linkifier).
|
|
|
|
The order of the array reflects the order that each
|
|
linkifier should be processed when linkifying messages
|
|
and topics. By default, new linkifiers are ordered
|
|
last. This order can be modified with [`PATCH
|
|
/realm/linkifiers`](/api/reorder-linkifiers).
|
|
|
|
Clients will receive an empty array unless the event queue is
|
|
registered with the client capability `{"linkifier_url_template": true}`.
|
|
See [`client_capabilities`](/api/register-queue#parameter-client_capabilities)
|
|
parameter for how this can be specified.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 176), the
|
|
`linkifier_url_template` client capability was not required. The
|
|
requirement was added because linkifiers were updated to contain
|
|
a URL template instead of a URL format string, which was a not
|
|
backwards-compatible change.
|
|
|
|
New in Zulip 4.0 (feature level 54). Clients can access this data for
|
|
servers on earlier feature levels via the legacy `realm_filters` property.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
|
|
pattern which represents the pattern that should be linkified on matching.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL
|
|
template with which the pattern matching string should be linkified.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
realm_filters:
|
|
type: array
|
|
deprecated: true
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
description: |
|
|
Legacy property for [linkifiers](/help/add-a-custom-linkifier).
|
|
Present if `realm_filters` is present in `fetch_event_types`.
|
|
|
|
When present, this is always an empty array.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 176), this was
|
|
an array of tuples, where each tuple described a linkifier. The first
|
|
element of the tuple was a string regex pattern which represented the
|
|
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
|
|
The second element was a URL format string that the pattern should be
|
|
linkified with. A URL format string for the above example would be
|
|
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
|
|
was the ID of the realm filter.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 54), replaced by the
|
|
`realm_linkifiers` key.
|
|
realm_playgrounds:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RealmPlayground"
|
|
description: |
|
|
Present if `realm_playgrounds` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a
|
|
[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
realm_user_groups:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/UserGroup"
|
|
description: |
|
|
Present if `realm_user_groups` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a
|
|
[user group](/help/user-groups) in the Zulip organization.
|
|
|
|
Deactivated groups will only be included if `include_deactivated_groups`
|
|
client capability is set to `true`.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 294), deactivated
|
|
groups were included for all the clients.
|
|
realm_bots:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Bot"
|
|
description: |
|
|
Present if `realm_bot` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a bot that the
|
|
current user can administer. If the current user is an organization
|
|
administrator, this will include all bots in the organization. Otherwise,
|
|
it will only include bots owned by the user (either because the user created
|
|
the bot or an administrator transferred the bot's ownership to the user).
|
|
realm_embedded_bots:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of an embedded bot. Embedded bots are an experimental
|
|
feature not enabled in production yet.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the bot.
|
|
config:
|
|
$ref: "#/components/schemas/BotConfiguration"
|
|
description: |
|
|
Present if `realm_embedded_bots` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes an type of embedded
|
|
bot that is available to be configured on this Zulip server.
|
|
|
|
Clients only need these data if they contain UI for creating or administering bots.
|
|
realm_incoming_webhook_bots:
|
|
description: |
|
|
Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a type of incoming webhook
|
|
integration that is available to be configured on this Zulip server.
|
|
|
|
Clients only need these data if they contain UI for creating or administering bots.
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the bot.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
A machine-readable unique name identifying the integration, all-lower-case without
|
|
spaces.
|
|
display_name:
|
|
type: string
|
|
description: |
|
|
A human-readable display name identifying the integration that this bot implements,
|
|
intended to be used in menus for selecting which integration to create.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 207).
|
|
all_event_types:
|
|
type: array
|
|
items:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
For incoming webhook integrations that support the Zulip server filtering incoming
|
|
events, the list of event types supported by it.
|
|
|
|
A null value will be present if this incoming webhook integration doesn't support
|
|
such filtering.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 207).
|
|
config_options:
|
|
$ref: "#/components/schemas/WebhookConfigOption"
|
|
recent_private_conversations:
|
|
description: |
|
|
Present if `recent_private_conversations` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries containing data on all direct message and group direct message
|
|
conversations that the user has received (or sent) messages in, organized by
|
|
conversation. This data set is designed to support UI elements such as the
|
|
"Direct messages" widget in the web application showing recent direct message
|
|
conversations that the user has participated in.
|
|
|
|
"Recent" is defined as the server's discretion; the original implementation
|
|
interpreted that as "the 1000 most recent direct messages the user received".
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object describing a single recent direct conversation in the user's history.
|
|
properties:
|
|
max_message_id:
|
|
type: integer
|
|
description: |
|
|
The highest message ID of the conversation, intended to support sorting
|
|
the conversations by recency.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
The list of users other than the current user in the direct message
|
|
conversation. This will be an empty list for direct messages sent to
|
|
oneself.
|
|
saved_snippets:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/SavedSnippet"
|
|
description: |
|
|
Present if `saved_snippets` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries containing data on all of the current user's
|
|
saved snippets.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 297).
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes the properties
|
|
of a channel the user is subscribed to (as well as that user's
|
|
personal per-channel settings).
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 8.0 (feature level 226).
|
|
|
|
Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
unsubscribed:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes one of the
|
|
channels the user has unsubscribed from but was previously subscribed to
|
|
along with the subscription details.
|
|
|
|
Unlike `never_subscribed`, the user might have messages in their personal
|
|
message history that were sent to these channels.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 8.0 (feature level 226).
|
|
|
|
Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
never_subscribed:
|
|
type: array
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicChannelBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
is_archived: {}
|
|
description: {}
|
|
date_created: {}
|
|
creator_id:
|
|
nullable: true
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group: {}
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the channel per week, as
|
|
estimated based on recent weeks, rounded to the nearest integer.
|
|
|
|
If `null`, the channel was recently created and there is
|
|
insufficient data to estimate the average traffic.
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list of user IDs of users who are subscribed
|
|
to the channel. Included only if `include_subscribers` is `true`.
|
|
|
|
If a user is not allowed to know the subscribers for
|
|
a channel, we will send an empty array. API authors
|
|
should use other data to determine whether users like
|
|
guest users are forbidden to know the subscribers.
|
|
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes one of the
|
|
channels that is visible to the user and the user has never been subscribed
|
|
to.
|
|
|
|
Important for clients containing UI where one can browse channels to subscribe
|
|
to.
|
|
unread_msgs:
|
|
type: object
|
|
description: |
|
|
Present if `message` and `update_message_flags` are both present in
|
|
`event_types`.
|
|
|
|
A set of data structures describing the conversations containing
|
|
the 50000 most recent unread messages the user has received. This will usually
|
|
contain every unread message the user has received, but clients should support
|
|
users with even more unread messages (and not hardcode the number 50000).
|
|
additionalProperties: false
|
|
properties:
|
|
count:
|
|
type: integer
|
|
description: |
|
|
The total number of unread messages to display. This includes one-on-one and group
|
|
direct messages, as well as channel messages that are not [muted](/help/mute-a-topic).
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow
|
|
topic features were not handled correctly in calculating this field.
|
|
pms:
|
|
type: array
|
|
description: |
|
|
An array of objects where each object contains details of unread
|
|
one-on-one direct messages with a specific user.
|
|
|
|
Note that it is possible for a message that the current user sent
|
|
to the specified user to be marked as unread and thus appear here.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
other_user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the other participant in this one-on-one direct
|
|
message conversation. Will be the current user's ID for messages
|
|
that they sent in a one-on-one direct message conversation with
|
|
themself.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 119), replacing
|
|
the less clearly named `sender_id` field.
|
|
sender_id:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Old name for the `other_user_id` field. Clients should access
|
|
this field in Zulip server versions that do not yet support
|
|
`other_user_id`.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 119).
|
|
We expect to provide a next version of the full `unread_msgs`
|
|
API before removing this legacy name.
|
|
unread_message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread direct messages sent
|
|
by either user in this one-on-one direct message conversation,
|
|
sorted in ascending order.
|
|
items:
|
|
type: integer
|
|
streams:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains details of all
|
|
unread messages of a single subscribed channel. This includes muted channels
|
|
and muted topics, even though those messages are excluded from `count`.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 90), these objects
|
|
included a `sender_ids` property, which listed the set of IDs of
|
|
users who had sent the unread messages.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
topic:
|
|
type: string
|
|
description: |
|
|
The topic under which the messages were sent.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which the messages were sent.
|
|
unread_message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread messages sent in this channel,
|
|
sorted in ascending order.
|
|
items:
|
|
type: integer
|
|
huddles:
|
|
type: array
|
|
description: |
|
|
An array of objects where each object contains details of unread
|
|
group direct messages with a specific group of users.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
user_ids_string:
|
|
type: string
|
|
description: |
|
|
A string containing the IDs of all users in the group
|
|
direct message conversation, including the current user,
|
|
separated by commas and sorted numerically; for example:
|
|
`"1,2,3"`.
|
|
unread_message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread messages which have been sent in
|
|
this group direct message conversation, sorted in ascending order.
|
|
items:
|
|
type: integer
|
|
mentions:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of all unread messages in which the user was
|
|
mentioned directly, and unread [non-muted](/help/mute-a-topic) messages
|
|
in which the user was mentioned through a wildcard.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow
|
|
topic features were not handled correctly in calculating this field.
|
|
items:
|
|
type: integer
|
|
old_unreads_missing:
|
|
type: boolean
|
|
description: |
|
|
Whether this data set was truncated because the user has too many
|
|
unread messages. When truncation occurs, only the most recent
|
|
`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered
|
|
when forming this response. When `true`, we recommend that clients
|
|
display a warning, as they are likely to produce erroneous results
|
|
until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`
|
|
unread messages.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 44).
|
|
starred_messages:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Present if `starred_messages` is present in `fetch_event_types`.
|
|
|
|
Array containing the IDs of all messages which have been
|
|
[starred](/help/star-a-message) by the user.
|
|
streams:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/BasicChannel"
|
|
description: |
|
|
Present if `stream` is present in `fetch_event_types`.
|
|
|
|
Array of dictionaries where each dictionary contains details about
|
|
a single channel in the organization that is visible to the user.
|
|
|
|
For organization administrators, this will include all private channels
|
|
in the organization.
|
|
|
|
**Changes**: As of Zulip 8.0 (feature level 205), this will include all
|
|
web-public channels in the organization as well.
|
|
realm_default_streams:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/DefaultChannel"
|
|
description: |
|
|
Present if `default_streams` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains details
|
|
about a single [default channel](/help/set-default-channels-for-new-users)
|
|
for the Zulip organization.
|
|
realm_default_stream_groups:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/DefaultChannelGroup"
|
|
description: |
|
|
Present if `default_stream_groups` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains details
|
|
about a single default channel group configured for this
|
|
Zulip organization.
|
|
|
|
Default channel groups are an experimental feature.
|
|
stop_words:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Present if `stop_words` is present in `fetch_event_types`.
|
|
|
|
An array containing the stop words used by the Zulip server's
|
|
full-text search implementation. Useful for showing helpful
|
|
error messages when a search returns limited results because
|
|
a stop word in the query was ignored.
|
|
user_status:
|
|
type: object
|
|
description: |
|
|
Present if `user_status` is present in `fetch_event_types`.
|
|
|
|
A dictionary which contains the [status](/help/status-and-availability)
|
|
of all users in the Zulip organization who have set a status.
|
|
|
|
**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).
|
|
Previously, Zulip did not support emoji associated with statuses.
|
|
additionalProperties:
|
|
allOf:
|
|
- description: |
|
|
`{user_id}`: Object containing the status details of a user
|
|
with the key of the object being the ID of the user.
|
|
- $ref: "#/components/schemas/UserStatus"
|
|
user_settings:
|
|
type: object
|
|
description: |
|
|
Present if `user_settings` is present in `fetch_event_types`.
|
|
|
|
A dictionary containing the user's personal settings.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 89). Previously,
|
|
these settings appeared in the top-level object, where they are
|
|
available for clients without the `user_settings_object` client
|
|
capability for backwards-compatibility.
|
|
additionalProperties: false
|
|
properties:
|
|
twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
dense_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
web_mark_read_on_scroll_policy:
|
|
type: integer
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
web_channel_default_view:
|
|
type: integer
|
|
description: |
|
|
Web/desktop app setting controlling the default navigation
|
|
behavior when clicking on a channel link.
|
|
|
|
- 1 - Top topic in the channel
|
|
- 2 - Channel feed
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
|
|
was not configurable, and every user had the "Channel feed" behavior.
|
|
starred_message_counts:
|
|
type: boolean
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
receives_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is configured to receive typing notifications from
|
|
other users. The server will only deliver typing notifications events
|
|
to users who for whom this is enabled.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
|
|
only options to disable sending typing notifications.
|
|
fluid_layout_width:
|
|
type: boolean
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
high_contrast_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
web_font_size_px:
|
|
description: |
|
|
User-configured primary `font-size` for the web application, in pixels.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
|
|
only adjustable via browser zoom. Note that this setting was not fully
|
|
implemented at this feature level.
|
|
type: integer
|
|
example: 14
|
|
web_line_height_percent:
|
|
description: |
|
|
User-configured primary `line-height` for the web application, in percent, so a
|
|
value of 120 represents a `line-height` of 1.2.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
|
|
not user-configurable. Note that this setting was not fully implemented at this
|
|
feature level.
|
|
type: integer
|
|
example: 122
|
|
color_scheme:
|
|
type: integer
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
translate_emoticons:
|
|
type: boolean
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
display_emoji_reaction_users:
|
|
type: boolean
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting
|
|
users, rather than a count, for messages with few total
|
|
reactions. The ideal cutoff may depend on the space
|
|
available for displaying reactions; the official web
|
|
application displays names when 3 or fewer total reactions
|
|
are present with this setting enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
web_home_view:
|
|
type: string
|
|
description: |
|
|
The [home view](/help/configure-home-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "inbox" - Inbox view
|
|
- "all_messages" - Combined feed view
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
|
|
called `default_view`, which was new in Zulip 4.0 (feature level 42).
|
|
web_escape_navigates_to_home_view:
|
|
type: boolean
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured home view](/help/configure-home-view).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
|
|
was called `escape_navigates_to_default_view`, which was new in Zulip
|
|
5.0 (feature level 107).
|
|
left_side_userlist:
|
|
type: boolean
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
emojiset:
|
|
type: string
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
demote_inactive_streams:
|
|
type: integer
|
|
description: |
|
|
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
user_list_style:
|
|
type: integer
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
web_animate_image_previews:
|
|
type: string
|
|
description: |
|
|
Controls how animated images should be played in the message feed in the web/desktop application.
|
|
|
|
- "always" - Always play the animated images in the message feed.
|
|
- "on_hover" - Play the animated images on hover over them in the message feed.
|
|
- "never" - Never play animated images in the message feed.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 275).
|
|
web_stream_unreads_count_display_policy:
|
|
type: integer
|
|
description: |
|
|
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
|
|
Channels that do not have an unread count will have a simple dot indicator for whether there are any
|
|
unread messages.
|
|
|
|
- 1 - All channels
|
|
- 2 - Unmuted channels and topics
|
|
- 3 - No channels
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 210).
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
|
|
enter_sends:
|
|
type: boolean
|
|
description: |
|
|
Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)
|
|
in the compose box is enabled.
|
|
enable_drafts_synchronization:
|
|
type: boolean
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
enable_stream_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for channel messages.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for channel messages.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notifications for channel messages.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for channel messages.
|
|
notification_sound:
|
|
type: string
|
|
description: |
|
|
Notification sound name.
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for direct messages and @-mentions.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for direct messages and
|
|
@-mentions.
|
|
enable_followed_topic_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable push notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
email_notifications_batching_period_seconds:
|
|
type: integer
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for direct messages and @-mentions received
|
|
when the user is offline.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is offline.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is online.
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
enable_marketing_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
enable_login_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
pm_content_in_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include content of direct messages in desktop notifications.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
|
|
should send notifications like a personal mention.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
desktop_icon_count_display:
|
|
type: integer
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unread messages
|
|
- 2 - DMs, mentions, and followed topics
|
|
- 3 - DMs and mentions
|
|
- 4 - None
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,
|
|
and followed topics` option, renumbering the options to insert it in
|
|
order.
|
|
realm_name_in_email_notifications_policy:
|
|
type: integer
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
automatically_follow_topics_policy:
|
|
type: integer
|
|
description: |
|
|
Which [topics to follow automatically](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
type: integer
|
|
description: |
|
|
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
automatically_follow_topics_where_mentioned:
|
|
type: boolean
|
|
description: |
|
|
Whether the server will automatically mark the user as following
|
|
topics where the user is mentioned.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 235).
|
|
presence_enabled:
|
|
type: boolean
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
available_notification_sounds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Array containing the names of the notification sound options
|
|
supported by this Zulip server. Only relevant to support UI
|
|
for configuring notification sounds.
|
|
emojiset_choices:
|
|
description: |
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
send_private_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has chosen to send [typing
|
|
notifications](/help/typing-notifications)
|
|
when composing direct messages. The client should send typing
|
|
notifications for direct messages if and only if this setting is enabled.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_stream_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has chosen to send [typing
|
|
notifications](/help/typing-notifications)
|
|
when composing channel messages. The client should send typing
|
|
notifications for channel messages if and only if this setting is enabled.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
allow_private_data_export:
|
|
type: boolean
|
|
description: |
|
|
Whether organization administrators are allowed to
|
|
export your private data.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 293).
|
|
email_address_visibility:
|
|
$ref: "#/components/schemas/EmailAddressVisibility"
|
|
web_navigate_to_sent_message:
|
|
type: boolean
|
|
description: |
|
|
Web/desktop app setting for whether the user's view should
|
|
automatically go to the conversation where they sent a message.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
|
|
this behavior was not configurable.
|
|
user_topics:
|
|
type: array
|
|
description: |
|
|
Present if `user_topic` is present in `fetch_event_types`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 134), deprecating and
|
|
replacing the previous `muted_topics` structure.
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing the user's configuration for a given topic.
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the channel to which the topic belongs.
|
|
topic_name:
|
|
type: string
|
|
description: |
|
|
The name of the topic.
|
|
last_updated:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user-topic
|
|
relationship was changed.
|
|
visibility_policy:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the user's visibility configuration for
|
|
the topic.
|
|
|
|
- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).
|
|
- 2 = Unmuted. Used to record [unmuted topics](/help/mute-a-topic).
|
|
- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 219), added followed as
|
|
a visibility policy option.
|
|
|
|
In Zulip 7.0 (feature level 170), added unmuted as a visibility
|
|
policy option.
|
|
has_zoom_token:
|
|
type: boolean
|
|
description: |
|
|
Present if `video_calls` is present in `fetch_event_types`.
|
|
|
|
A boolean which signifies whether the user has a zoom token and has thus completed
|
|
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
|
|
to know whether initiating Zoom OAuth is required before creating a Zoom call.
|
|
giphy_api_key:
|
|
type: string
|
|
description: |
|
|
Present if `giphy` is present in `fetch_event_types`.
|
|
|
|
GIPHY's client-side SDKs needs this API key to use the GIPHY API.
|
|
GIPHY API keys are not secret (their main purpose appears to be
|
|
allowing GIPHY to block a problematic app). Please don't use our API
|
|
key for an app unrelated to Zulip.
|
|
|
|
Developers of clients should also read the
|
|
[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)
|
|
before using this API key.
|
|
|
|
**Changes**: Added in Zulip 4.0 (feature level 47).
|
|
enable_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_digest_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_login_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_marketing_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
email_notifications_batching_period_seconds:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_offline_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_offline_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_online_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_sounds:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_audible_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
wildcard_mentions_notify:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
message_content_in_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
notification_sound:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
pm_content_in_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
desktop_icon_count_display:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
realm_name_in_email_notifications_policy:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 168), replaced previous
|
|
`realm_name_in_notifications` global notifications setting with
|
|
`realm_name_in_email_notifications_policy`.
|
|
|
|
**Deprecated** since Zulip 5.0 (feature level 89); both
|
|
`realm_name_in_notifications` and the newer
|
|
`realm_name_in_email_notifications_policy` are deprecated. Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
presence_enabled:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
available_notification_sounds:
|
|
deprecated: true
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Array containing the names of the notification sound options supported by
|
|
this Zulip server. Only relevant to support UI for configuring notification
|
|
sounds.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
color_scheme:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The color scheme selected by the user.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
default_language:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The default language chosen by the user.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
demote_inactive_streams:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen to demote inactive channels.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
dense_mode:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has switched on dense mode. Dense mode is an experimental
|
|
feature that is only available in development environments.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
emojiset:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The name of the emoji set that the user has chosen.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_drafts_synchronization:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether drafts synchronization is enabled for the user. If disabled,
|
|
clients will receive an error when trying to use the `drafts` endpoints.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
New in Zulip 5.0 (feature level 87).
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
fluid_layout_width:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for the layout width to be fluid.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
web_home_view:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The [home view](/help/configure-home-view) in Zulip, represented
|
|
as the URL suffix after `#` to be rendered when Zulip loads.
|
|
|
|
Currently supported values are `all_messages` and `recent_topics`.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
|
|
called `default_view`, which was new in Zulip 4.0 (feature level 42).
|
|
|
|
**Deprecated** in Zulip 5.0 (feature level 89). Clients connecting to newer
|
|
servers should declare the `user_settings_object` client capability and
|
|
access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
high_contrast_mode:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether has switched on high contrast mode.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
left_side_userlist:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for the userlist to be displayed
|
|
on the left side of the screen (for desktop app and web app) in narrow
|
|
windows.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
starred_message_counts:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen the number of starred messages to
|
|
be displayed similar to unread counts.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
timezone:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The time zone configured for the user. This is used primarily to display
|
|
the user's time zone to other users.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
translate_emoticons:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for emoticons to be translated into emoji
|
|
in the Zulip compose box.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
twenty_four_hour_time:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen a twenty four hour time display (true)
|
|
or a twelve hour one (false).
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
receives_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is configured to receive typing notifications from other
|
|
users. The server will only deliver typing notifications events to users who
|
|
for whom this is enabled.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
|
|
only options to disable sending typing notifications.
|
|
enter_sends:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user setting for [sending on pressing Enter][set-enter-send]
|
|
in the compose box is enabled.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
|
|
Prior to Zulip 5.0 (feature level 84), this field was present
|
|
in response if `realm_user` was present in `fetch_event_types`, not
|
|
`update_display_settings`.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
[set-enter-send]: /help/configure-send-message-keys
|
|
emojiset_choices:
|
|
deprecated: true
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
realm_allow_edit_history:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization is configured to allow users to access
|
|
[message edit history](/help/view-a-messages-edit-history).
|
|
realm_can_add_custom_emoji_group:
|
|
allOf:
|
|
- description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to add custom emoji in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 307). Previously, this
|
|
permission was controlled by the enum `add_custom_emoji_policy`. Values
|
|
were 1=Members, 2=Admins, 3=Full members, 4=Moderators.
|
|
|
|
Before Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only`
|
|
boolean setting controlled this permission; `true` corresponded to `Admins`,
|
|
and `false` to `Everyone`.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_can_delete_any_message_group:
|
|
allOf:
|
|
- description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to delete any message in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 281). Previously, this
|
|
permission was limited to administrators only and was uneditable.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_can_delete_own_message_group:
|
|
allOf:
|
|
- description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to delete messages that they have sent in the
|
|
organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 291). Previously, this
|
|
permission was controlled by the enum `delete_own_message_policy`. Values
|
|
were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.
|
|
|
|
Before Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean
|
|
setting controlled this permission; `true` corresponded to `Everyone`, and
|
|
`false` to `Admins`.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_can_move_messages_between_channels_group:
|
|
allOf:
|
|
- description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to move messages from one channel to another
|
|
in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 310). Previously, this
|
|
permission was controlled by the enum `move_messages_between_streams_policy`.
|
|
Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.
|
|
|
|
In Zulip 7.0 (feature level 159), `Nobody` was added as an option to
|
|
`move_messages_between_streams_policy` enum.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_can_move_messages_between_topics_group:
|
|
allOf:
|
|
- description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to move messages from one topic to another
|
|
within a channel in the organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 316). Previously, this
|
|
permission was controlled by the enum `edit_topic_policy`. Values were
|
|
1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.
|
|
|
|
In Zulip 7.0 (feature level 159), `Nobody` was added as an option to
|
|
`edit_topic_policy` enum.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create bot users in this organization.
|
|
realm_can_create_groups:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create user
|
|
groups in this organization.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 299). Previously
|
|
`realm_user_group_edit_policy` field used to control the
|
|
permission to create user groups.
|
|
realm_can_manage_all_groups:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values)
|
|
defining the set of users who have permission to
|
|
administer all existing groups in this organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 305), only users who
|
|
were a member of the group or had the moderator role or above could
|
|
exercise the permission on a given group.
|
|
|
|
New in Zulip 10.0 (feature level 299). Previously the
|
|
`user_group_edit_policy` field controlled the permission
|
|
to manage user groups. Valid values were as follows:
|
|
|
|
- 1 = All members can create and edit user groups
|
|
- 2 = Only organization administrators can create and edit
|
|
user groups
|
|
- 3 = Only [full members][calc-full-member] can create and
|
|
edit user groups.
|
|
- 4 = Only organization administrators and moderators can
|
|
create and edit user groups.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_can_create_public_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create public
|
|
channels in this organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 264). Previously
|
|
`realm_create_public_stream_policy` field used to control the
|
|
permission to create public channels.
|
|
realm_can_create_private_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create private
|
|
channels in this organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 266). Previously
|
|
`realm_create_private_stream_policy` field used to control the
|
|
permission to create private channels.
|
|
realm_can_create_web_public_channel_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining
|
|
the set of users who have permission to create web-public
|
|
channels in this organization.
|
|
|
|
Has no effect and should not be displayed in settings UI
|
|
unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
server-level setting enabled and the organization has enabled
|
|
the `enable_spectator_access` realm setting.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 280). Previously
|
|
`realm_create_web_public_stream_policy` field used to control
|
|
the permission to create web-public channels.
|
|
realm_create_public_stream_policy:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A deprecated representation of a superset of the users who
|
|
have permission to create public channels in the organization,
|
|
available for backwards-compatibility. Clients should use
|
|
`can_create_public_channel_group` instead.
|
|
|
|
It is an enum with the following possible values, corresponding
|
|
to roles/system groups:
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Admins and moderators only
|
|
|
|
**Changes**: Deprecated in Zulip 9.0 (feature level 264) and
|
|
replaced by `realm_can_create_public_channel_group`, which
|
|
supports finer resolution of configurations, resulting in this
|
|
property being inaccurate following that transition.
|
|
|
|
Before Zulip 5.0 (feature level 102), permission to create
|
|
channels was controlled by the `realm_create_stream_policy` setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_create_private_stream_policy:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A deprecated representation of a superset of the users who
|
|
have permission to create private channels in the organization,
|
|
available for backwards-compatibility. Clients should use
|
|
`can_create_private_channel_group` instead.
|
|
|
|
It is an enum with the following possible values, corresponding
|
|
to roles/system groups:
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Admins and moderators only
|
|
|
|
**Changes**: Deprecated in Zulip 9.0 (feature level 266) and
|
|
replaced by `realm_can_create_private_channel_group`, which
|
|
supports finer resolution of configurations, resulting in this
|
|
property being inaccurate following that transition.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 102), permission to
|
|
create channels was controlled by the `realm_create_stream_policy` setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_create_web_public_stream_policy:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A deprecated representation of a superset of the users who
|
|
have permission to create web-public channels in the
|
|
organization, available for backwards-compatibility. Clients
|
|
should use `can_create_web_public_channel_group` instead.
|
|
|
|
It is an enum with the following possible values, corresponding
|
|
to roles/system groups:
|
|
|
|
- 2 = Admins only
|
|
- 4 = Admins and moderators only
|
|
- 6 = Nobody
|
|
- 7 = Owners only
|
|
|
|
**Changes**: Deprecated in Zulip 10.0 (feature level 280) and
|
|
replaced by `realm_can_create_web_public_channel_group`, which
|
|
supports finer resolution of configurations, resulting in this
|
|
property being inaccurate following that transition.
|
|
|
|
**Changes**: Added in Zulip 5.0 (feature level 103).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
realm_invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can add other users to channels in this organization.
|
|
realm_wildcard_mention_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for who can use wildcard mentions
|
|
in large channels.
|
|
|
|
- 1 = Any user can use wildcard mentions in large channels.
|
|
- 2 = Only members can use wildcard mentions in large channels.
|
|
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.
|
|
- 5 = Only organization administrators can use wildcard mentions in large channels.
|
|
- 6 = Nobody can use wildcard mentions in large channels.
|
|
- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.
|
|
|
|
All users will receive a warning/reminder when using
|
|
mentions in large channels, even when permitted to do so.
|
|
|
|
**Changes**: In Zulip 6.0 (feature level 133), channel administrators option removed.
|
|
|
|
In Zulip 4.0 (feature level 62), moderators option added.
|
|
|
|
New in Zulip 4.0 (feature level 33).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_default_language:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [organization language][org-lang] for automated messages and invitation emails.
|
|
|
|
[org-lang]: /help/configure-organization-language
|
|
realm_description:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The description of the organization, used on login and registration pages.
|
|
realm_digest_emails_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
|
|
realm_disallow_disposable_email_addresses:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization disallows disposable email
|
|
addresses.
|
|
realm_email_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether users are allowed to change their own email address in this
|
|
organization. This is typically disabled for organizations that
|
|
synchronize accounts from LDAP or a similar corporate database.
|
|
realm_invite_required:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether an invitation is required to join this organization.
|
|
realm_invite_to_realm_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
[Policy][permission-level] for [who can invite new
|
|
users](/help/restrict-account-creation#change-who-can-send-invitations)
|
|
to join the organization:
|
|
|
|
- 1 = Members only
|
|
- 2 = Administrators only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 6 = Nobody
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
|
|
previous `realm_invite_by_admins_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_create_multiuse_invite_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the
|
|
set of users who are allowed to create [reusable invitation
|
|
links](/help/invite-new-users#create-a-reusable-invitation-link)
|
|
to the organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 314), this value used
|
|
to be of type integer and did not accept anonymous user groups.
|
|
|
|
New in Zulip 8.0 (feature level 209).
|
|
realm_inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization has been configured to enable
|
|
[previews of linked images](/help/image-video-and-website-previews).
|
|
realm_inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization has been configured to enable
|
|
[previews of linked websites](/help/image-video-and-website-previews).
|
|
realm_mandatory_topics:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether [topics are required](/help/require-topics) for messages in this organization.
|
|
realm_message_retention_days:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The default [message retention policy](/help/message-retention-policy)
|
|
for this organization. It can have one special value:
|
|
|
|
- `-1` denoting that the messages will be retained forever for this realm, by default.
|
|
|
|
**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was
|
|
encoded as `null` instead of `-1`. Clients can correctly handle all
|
|
server versions by treating both `-1` and `null` as indicating
|
|
unlimited message retention.
|
|
realm_name:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The name of the organization, used in login pages etc.
|
|
realm_require_unique_names:
|
|
type: boolean
|
|
description: |
|
|
Indicates whether the organization is configured to require users
|
|
to have unique full names. If true, the server will reject attempts
|
|
to create a new user, or change the name of an existing user, where
|
|
doing so would lead to two users whose names are identical modulo
|
|
case and unicode normalization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip
|
|
server could not be configured to enforce unique names.
|
|
realm_name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their name
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
realm_avatar_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their avatar
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
realm_emails_restricted_to_domains:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
this organization are required to have an email
|
|
address in one of the `realm_domains` configured for the organization.
|
|
realm_send_welcome_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether or not this organization is configured to send the standard Zulip
|
|
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
|
|
realm_message_content_allowed_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether notification emails in this organization are allowed to
|
|
contain Zulip the message content, or simply indicate that a new
|
|
message was sent.
|
|
realm_enable_spectator_access:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether web-public channels and related anonymous access APIs/features
|
|
are enabled in this organization.
|
|
|
|
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
[server setting][server-settings] is enabled on the Zulip
|
|
server. See also the `can_create_web_public_channel_group` realm
|
|
setting.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 109).
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
realm_want_advertise_in_communities_directory:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has given permission to be advertised in the
|
|
Zulip [communities directory](/help/communities-directory).
|
|
|
|
Useful only to clients supporting changing this setting for the
|
|
organization.
|
|
|
|
Giving permission via this setting does not guarantee that an
|
|
organization will be listed in the Zulip communities directory.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 129).
|
|
realm_video_chat_provider:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The configured [video call provider](/help/start-a-call) for the
|
|
organization.
|
|
|
|
- 0 = None
|
|
- 1 = Jitsi Meet
|
|
- 3 = Zoom
|
|
- 4 = BigBlueButton
|
|
|
|
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
|
|
to disable video call UI.
|
|
realm_jitsi_server_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the custom Jitsi Meet server configured in this organization's
|
|
settings.
|
|
|
|
`null`, the default, means that the organization is using the should use the
|
|
server-level configuration, `server_jitsi_server_url`. A correct client
|
|
supporting only the modern API should use `realm_jitsi_server_url ||
|
|
server_jitsi_server_url` to create calls.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only
|
|
available as a server-level configuration, which was available via the
|
|
`jitsi_server_url` field.
|
|
realm_giphy_rating:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The configured GIPHY rating for the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 55).
|
|
realm_waiting_period_threshold:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Members whose accounts have been created at least this many days ago
|
|
will be treated as [full members][calc-full-member]
|
|
for the purpose of settings that restrict access to new members.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_digest_weekday:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The day of the week when the organization will send
|
|
its weekly digest email to inactive users.
|
|
realm_direct_message_initiator_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to start a new direct message conversation
|
|
involving other non-bot users. Users who are outside this group and attempt
|
|
to send the first direct message to a given collection of recipient users
|
|
will receive an error, unless all other recipients are bots or the sender.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 270).
|
|
|
|
Previously, access to send direct messages was controlled by the
|
|
`private_message_policy` realm setting, which supported values of
|
|
1 (enabled) and 2 (disabled).
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_direct_message_permission_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the set of
|
|
users who have permission to fully use direct messages. Users outside
|
|
this group can only send direct messages to conversations where all the
|
|
recipients are in this group, are bots, or are the sender, ensuring that
|
|
every direct message conversation will be visible to at least one user in
|
|
this group.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 270).
|
|
|
|
Previously, access to send direct messages was controlled by the
|
|
`private_message_policy` realm setting, which supported values of
|
|
1 (enabled) and 2 (disabled).
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
realm_default_code_block_language:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The default pygments language code to be used for code blocks in this
|
|
organization. If an empty string, no default has been set.
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant
|
|
that both `null` and an empty string could represent that no default was
|
|
set for this realm setting. Clients supporting older server versions
|
|
should treat either value (`null` or `""`) as no default being set.
|
|
realm_message_content_delete_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be deleted
|
|
with this organization's
|
|
[message deletion policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be 0. A `null` value means no limit: messages can be deleted
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 5.0 (feature level 100).
|
|
realm_authentication_methods:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmAuthenticationMethod"
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary of authentication method keys mapped to dictionaries that
|
|
describe the properties of the named authentication method for the
|
|
organization - its enabled status and availability for use by the
|
|
organization.
|
|
|
|
Clients should use this to implement server-settings UI to change which
|
|
methods are enabled for the organization. For authentication UI itself,
|
|
clients should use the pre-authentication metadata returned by
|
|
[`GET /server_settings`](/api/get-server-settings).
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 241), the values in this
|
|
dictionary were changed. Previously, the values were a simple boolean
|
|
indicating whether the backend is enabled or not.
|
|
realm_allow_message_editing:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization's [message edit policy][config-message-editing]
|
|
allows editing the content of messages.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
[config-message-editing]: /help/restrict-message-editing-and-deletion
|
|
realm_message_content_edit_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be edited
|
|
with this organization's
|
|
[message edit policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be `0`. A `null` value means no limit, so messages can be edited
|
|
regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 138), no limit was
|
|
represented using the special value `0`.
|
|
realm_move_messages_within_stream_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be moved within a
|
|
channel to another topic by users who have permission to do so based on this
|
|
organization's [topic edit policy](/help/restrict-moving-messages). This
|
|
setting does not affect moderators and administrators.
|
|
|
|
Will not be `0`. A `null` value means no limit, so message topics can be
|
|
edited regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
|
|
limit was always 72 hours for users who were not administrators or
|
|
moderators.
|
|
realm_move_messages_between_streams_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be moved between
|
|
channels by users who have permission to do so based on this organization's
|
|
[message move policy](/help/restrict-moving-messages). This setting does
|
|
not affect moderators and administrators.
|
|
|
|
Will not be `0`. A `null` value means no limit, so messages can be moved
|
|
regardless of how long ago they were sent.
|
|
|
|
See [`PATCH /messages/{message_id}`](/api/update-message) for details and
|
|
history of how message editing permissions work.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
|
|
no time limit for moving messages between channels for users with permission
|
|
to do so.
|
|
realm_enable_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether read receipts is enabled in the organization or not.
|
|
|
|
If disabled, read receipt data will be unavailable to clients, regardless
|
|
of individual users' personal read receipt settings. See also the
|
|
`send_read_receipts` setting within `realm_user_settings_defaults`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
realm_icon_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's [profile icon](/help/create-your-organization-profile).
|
|
realm_icon_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's
|
|
[profile icon](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the organization's icon.
|
|
|
|
- "G" means generated by Gravatar (the default).
|
|
- "U" means uploaded by an organization administrator.
|
|
max_icon_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size allowed for the organization's
|
|
icon. Useful for UI allowing editing the organization's icon.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `max_icon_file_size`.
|
|
realm_logo_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's wide logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
realm_logo_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
realm_night_logo_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's dark theme wide-format logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
realm_night_logo_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's dark theme
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
max_logo_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size allowed for the uploaded organization logos.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `max_logo_file_size`.
|
|
realm_bot_domain:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The fake email domain that will be used for new bots created this
|
|
organization. Useful for UI for creating bots.
|
|
realm_uri:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL for the organization. Alias of `realm_url`.
|
|
|
|
**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term
|
|
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
|
|
realm_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL for the organization.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 257), replacing the
|
|
deprecated `realm_uri`.
|
|
realm_available_video_chat_providers:
|
|
type: object
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary where each entry describes a supported
|
|
[video call provider](/help/start-a-call)
|
|
that is configured on this server and could be selected by an
|
|
organization administrator.
|
|
|
|
Useful for administrative settings UI that allows changing the
|
|
realm setting `video_chat_provider`.
|
|
additionalProperties:
|
|
description: |
|
|
`{provider_name}`: Dictionary containing the details of the
|
|
video call provider with the name of the chat provider as
|
|
the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the video call provider.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the video call provider.
|
|
realm_presence_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether online presence of other users is shown in this
|
|
organization.
|
|
settings_send_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this Zulip server is configured to allow organizations to
|
|
enable [digest emails](/help/digest-emails).
|
|
|
|
Relevant for administrative settings UI that can change the digest
|
|
email settings.
|
|
realm_is_zephyr_mirror_realm:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization is a Zephyr mirror realm.
|
|
realm_email_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has enabled Zulip's default email and password
|
|
authentication feature. Determines whether Zulip stores a password
|
|
for the user and clients should offer any UI for changing the user's
|
|
Zulip password.
|
|
realm_password_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization allows any sort of password-based
|
|
authentication (whether via EmailAuthBackend or LDAP passwords).
|
|
|
|
Determines whether a client might ever need to display a password prompt
|
|
(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)
|
|
before presenting a login page).
|
|
realm_push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether push notifications are enabled for this organization. Typically
|
|
`true` for Zulip Cloud and self-hosted realms that have a valid
|
|
registration for the [Mobile push notifications
|
|
service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),
|
|
and `false` for self-hosted servers that do not.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 231), this incorrectly was
|
|
`true` for servers that were partly configured to use the Mobile Push
|
|
Notifications Service but not properly registered.
|
|
realm_push_notifications_enabled_end_timestamp:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
If the server expects the realm's push notifications access to end at a
|
|
definite time in the future, the UNIX timestamp (UTC) at which this is
|
|
expected to happen. Mobile clients should use this field to display warnings
|
|
to users when the indicated timestamp is near.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 231).
|
|
realm_upload_quota_mib:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The total quota for uploaded files in this organization.
|
|
|
|
Clients are not responsible for checking this quota; it is included
|
|
in the API only for display purposes.
|
|
|
|
If `null`, there is no limit.
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 251), this field
|
|
was incorrectly measured in bytes, not MiB.
|
|
|
|
New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `realm_upload_quota`.
|
|
realm_org_type:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [organization type](/help/organization-type) for the realm.
|
|
Useful only to clients supporting changing this setting for the
|
|
organization, or clients implementing onboarding content or
|
|
other features that varies with organization type.
|
|
|
|
- 0 = Unspecified
|
|
- 10 = Business
|
|
- 20 = Open-source project
|
|
- 30 = Education (non-profit)
|
|
- 35 = Education (for-profit)
|
|
- 40 = Research
|
|
- 50 = Event or conference
|
|
- 60 = Non-profit (registered)
|
|
- 70 = Government
|
|
- 80 = Political group
|
|
- 90 = Community
|
|
- 100 = Personal
|
|
- 1000 = Other
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 128).
|
|
realm_plan_type:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The plan type of the organization.
|
|
|
|
- 1 = Self-hosted organization (SELF_HOSTED)
|
|
- 2 = Zulip Cloud free plan (LIMITED)
|
|
- 3 = Zulip Cloud Standard plan (STANDARD)
|
|
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
|
|
realm_enable_guest_user_indicator:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether clients should display "(guest)" after the names of
|
|
guest users to prominently highlight their status.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 216).
|
|
realm_can_access_all_users_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value](/api/group-setting-values) defining the
|
|
set of users who are allowed to access all users in the
|
|
organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 314), this value used
|
|
to be of type integer and did not accept anonymous user groups.
|
|
|
|
New in Zulip 8.0 (feature level 225).
|
|
zulip_plan_is_not_limited:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization is using a limited (Zulip Cloud Free) plan.
|
|
upgrade_text_for_wide_organization_logo:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Text to use when displaying UI for wide organization logos, a feature
|
|
that is currently not available on the Zulip Cloud Free plan.
|
|
|
|
Useful only for clients supporting administrative UI for uploading
|
|
a new wide organization logo to brand the organization.
|
|
realm_default_external_accounts:
|
|
type: object
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary where each entry describes a default external
|
|
account type that can be configured with Zulip's [custom
|
|
profile fields feature](/help/custom-profile-fields).
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
additionalProperties:
|
|
description: |
|
|
`{site_name}`: Dictionary containing the details of the
|
|
default external account provider with the name of the
|
|
website as the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the external account provider
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the external account.
|
|
hint:
|
|
type: string
|
|
description: |
|
|
The help text to be displayed for the
|
|
custom profile field in user-facing
|
|
settings UI for configuring custom
|
|
profile fields for this account.
|
|
url_pattern:
|
|
type: string
|
|
description: |
|
|
The regex pattern of the URL of a profile page
|
|
on the external site.
|
|
jitsi_server_url:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The base URL to be used to create Jitsi video calls. Equals
|
|
`realm_jitsi_server_url || server_jitsi_server_url`.
|
|
|
|
**Changes**: Deprecated in Zulip 8.0 (feature level 212) and will
|
|
eventually be removed. Previously, the Jitsi server to use was not
|
|
configurable on a per-realm basis, and this field contained the server's
|
|
configured Jitsi server. (Which is now provided as
|
|
`server_jitsi_server_url`). Clients supporting older versions should fall
|
|
back to this field when creating calls: using `realm_jitsi_server_url ||
|
|
server_jitsi_server_url` with newer servers and using `jitsi_server_url`
|
|
with servers below feature level 212.
|
|
development_environment:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this Zulip server is a development environment. Used
|
|
to control certain features or UI (such as error popups)
|
|
that should only apply when connected to a Zulip development
|
|
environment.
|
|
server_generation:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A timestamp indicating when the process hosting this
|
|
event queue was started. Clients will likely only find
|
|
this value useful for inclusion in detailed error reports.
|
|
password_min_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
This Zulip server's configured minimum required length for passwords.
|
|
Necessary for password change UI to show whether the password
|
|
will be accepted.
|
|
password_min_guesses:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
This Zulip server's configured minimum `zxcvbn` minimum guesses.
|
|
Necessary for password change UI to show whether the password
|
|
will be accepted.
|
|
giphy_rating_options:
|
|
type: object
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary where each entry describes a valid rating
|
|
that is configured on this server and could be selected by an
|
|
organization administrator.
|
|
|
|
Useful for administrative settings UI that allows changing the
|
|
allowed rating of GIFs.
|
|
additionalProperties:
|
|
description: |
|
|
`{rating_name}`: Dictionary containing the details of the
|
|
rating with the name of the rating as
|
|
the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The description of the rating option.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the rating option.
|
|
max_file_upload_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size that can be uploaded to this Zulip organization.
|
|
max_avatar_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum avatar size that can be uploaded to this Zulip server.
|
|
server_inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is configured with support for inline image previews.
|
|
Clients containing administrative UI for changing
|
|
`realm_inline_image_preview` should consult this field before offering
|
|
that feature.
|
|
server_inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is configured with support for inline URL previews.
|
|
Clients containing administrative UI for changing
|
|
`realm_inline_url_embed_preview` should consult this field before offering
|
|
that feature.
|
|
server_thumbnail_formats:
|
|
description: |
|
|
A list describing the image formats that uploaded
|
|
images will be thumbnailed into. Any image with a
|
|
source starting with `/user_uploads/thumbnail/` can
|
|
have its last path component replaced with any of the
|
|
names contained in this list, to obtain the desired
|
|
thumbnail size.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 273).
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The file path component of the thumbnail format.
|
|
max_width:
|
|
type: integer
|
|
description: |
|
|
The maximum width of this format.
|
|
max_height:
|
|
type: integer
|
|
description: |
|
|
The maximum height of this format.
|
|
format:
|
|
type: string
|
|
description: |
|
|
The extension of this format.
|
|
animated:
|
|
type: boolean
|
|
description: |
|
|
If this file format is animated. These formats
|
|
are only generated for uploaded imates which
|
|
themselves are animated.
|
|
server_avatar_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server allows avatar changes. Similar to
|
|
`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`
|
|
Zulip server level setting.
|
|
server_name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server allows name changes. Similar to
|
|
`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`
|
|
Zulip server level setting.
|
|
server_needs_upgrade:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is running an old version based on the Zulip
|
|
[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),
|
|
such that the web app will display to the current user a prominent warning.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 74).
|
|
server_web_public_streams_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level
|
|
setting. A server that has disabled this setting intends to not offer [web
|
|
public channels](/help/public-access-option) to realms it hosts. (Zulip Cloud
|
|
defaults to `true`; self-hosted servers default to `false`).
|
|
|
|
Clients should use this to determine whether to offer UI for the
|
|
realm-level setting for enabling web-public channels
|
|
(`realm_enable_spectator_access`).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 110).
|
|
server_emoji_data_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL to a JSON file that describes which emoji names map to which
|
|
emoji codes, for all Unicode emoji this Zulip server accepts.
|
|
|
|
The data at the given URL is a JSON object with one property, `code_to_names`.
|
|
The value of that property is a JSON object where each key is an
|
|
[emoji code](/api/add-reaction#parameter-emoji_code) for an available
|
|
Unicode emoji, and each value is the corresponding
|
|
[emoji names](/api/add-reaction#parameter-emoji_name) for this emoji,
|
|
with the canonical name for the emoji always appearing first.
|
|
|
|
The HTTP response at that URL will have appropriate HTTP caching headers, such
|
|
any HTTP implementation should get a cached version if emoji haven't changed
|
|
since the last request.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 140).
|
|
server_jitsi_server_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the Jitsi server that the Zulip server is configured to use by
|
|
default; the organization-level setting `realm_jitsi_server_url` takes
|
|
precedence over this setting when both are set.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this value
|
|
was available as the now-deprecated `jitsi_server_url`.
|
|
event_queue_longpoll_timeout_seconds:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Recommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.
|
|
This is guaranteed to be somewhat greater than the heartbeat frequency. It is important
|
|
that clients respect this parameter, so that increases in the heartbeat frequency do not
|
|
break clients.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 74). Previously,
|
|
this was hardcoded to 90 seconds, and clients should use that as a fallback
|
|
value when interacting with servers where this field is not present.
|
|
realm_new_stream_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The ID of the channel to which automated messages announcing the
|
|
[creation of new channels][new-channel-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 241), renamed 'realm_notifications_stream_id'
|
|
to `realm_new_stream_announcements_stream_id`.
|
|
realm_signup_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The ID of the channel to which automated messages announcing
|
|
that [new users have joined the organization][new-user-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-user-announce]: /help/configure-automated-notices#new-user-announcements
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 241), renamed
|
|
'realm_signup_notifications_stream_id' to `realm_signup_announcements_stream_id`.
|
|
realm_zulip_update_announcements_stream_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The ID of the channel to which automated messages announcing
|
|
new features or other end-user updates about the Zulip software are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 242).
|
|
realm_user_settings_defaults:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Present if `realm_user_settings_defaults` is present in `fetch_event_types`.
|
|
|
|
A dictionary containing the default values of settings for new users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 95).
|
|
properties:
|
|
twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 99).
|
|
This value was previously available as
|
|
`realm_default_twenty_four_hour_time` in
|
|
the top-level response object (only when `realm` was
|
|
present in `fetch_event_types`).
|
|
dense_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in
|
|
controlling the default font size in Zulip.
|
|
web_mark_read_on_scroll_policy:
|
|
type: integer
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
web_channel_default_view:
|
|
type: integer
|
|
description: |
|
|
Web/desktop app setting controlling the default navigation
|
|
behavior when clicking on a channel link.
|
|
|
|
- 1 - Top topic in the channel
|
|
- 2 - Channel feed
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
|
|
was not configurable, and every user had the "Channel feed" behavior.
|
|
starred_message_counts:
|
|
type: boolean
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
receives_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is configured to receive typing notifications from
|
|
other users. The server will only deliver typing notifications events
|
|
to users who for whom this is enabled.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
|
|
only options to disable sending typing notifications.
|
|
fluid_layout_width:
|
|
type: boolean
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
high_contrast_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
web_font_size_px:
|
|
description: |
|
|
User-configured primary `font-size` for the web application, in pixels.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
|
|
only adjustable via browser zoom. Note that this setting was not fully
|
|
implemented at this feature level.
|
|
type: integer
|
|
example: 14
|
|
web_line_height_percent:
|
|
description: |
|
|
User-configured primary `line-height` for the web application, in percent, so a
|
|
value of 120 represents a `line-height` of 1.2.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
|
|
not user-configurable. Note that this setting was not fully implemented at this
|
|
feature level.
|
|
type: integer
|
|
example: 122
|
|
color_scheme:
|
|
type: integer
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
translate_emoticons:
|
|
type: boolean
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
display_emoji_reaction_users:
|
|
type: boolean
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting
|
|
users, rather than a count, for messages with few total
|
|
reactions. The ideal cutoff may depend on the space
|
|
available for displaying reactions; the official web
|
|
application displays names when 3 or fewer total reactions
|
|
are present with this setting enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
web_home_view:
|
|
type: string
|
|
description: |
|
|
The [home view](/help/configure-home-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "inbox" - Inbox view
|
|
- "all_messages" - Combined feed view
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
|
|
called `default_view`, which was new in Zulip 4.0 (feature level 42).
|
|
web_escape_navigates_to_home_view:
|
|
type: boolean
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured home view](/help/configure-home-view).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
|
|
was called `escape_navigates_to_default_view`, which was new in Zulip
|
|
5.0 (feature level 107).
|
|
left_side_userlist:
|
|
type: boolean
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
emojiset:
|
|
type: string
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
demote_inactive_streams:
|
|
type: integer
|
|
description: |
|
|
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
user_list_style:
|
|
type: integer
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
web_animate_image_previews:
|
|
type: string
|
|
description: |
|
|
Controls how animated images should be played in the message feed in the web/desktop application.
|
|
|
|
- "always" - Always play the animated images in the message feed.
|
|
- "on_hover" - Play the animated images on hover over them in the message feed.
|
|
- "never" - Never play animated images in the message feed.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 275).
|
|
web_stream_unreads_count_display_policy:
|
|
type: integer
|
|
description: |
|
|
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
|
|
Channels that do not have an unread count will have a simple dot indicator for whether there are any
|
|
unread messages.
|
|
|
|
- 1 - All channels
|
|
- 2 - Unmuted channels and topics
|
|
- 3 - No channels
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 210).
|
|
enable_stream_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for channel messages.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for channel messages.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notifications for channel messages.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for channel messages.
|
|
notification_sound:
|
|
type: string
|
|
description: |
|
|
Notification sound name.
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for direct messages and @-mentions.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for direct messages and
|
|
@-mentions.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for direct messages and @-mentions received
|
|
when the user is offline.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is offline.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is online.
|
|
enable_followed_topic_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable push notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_followed_topic_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
enable_marketing_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
enable_login_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
pm_content_in_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include content of direct messages in desktop notifications.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
|
|
should send notifications like a personal mention.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
desktop_icon_count_display:
|
|
type: integer
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unread messages
|
|
- 2 - DMs, mentions, and followed topics
|
|
- 3 - DMs and mentions
|
|
- 4 - None
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,
|
|
and followed topics` option, renumbering the options to insert it in
|
|
order.
|
|
realm_name_in_email_notifications_policy:
|
|
type: integer
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
automatically_follow_topics_policy:
|
|
type: integer
|
|
description: |
|
|
Which [topics to follow automatically](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
type: integer
|
|
description: |
|
|
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
automatically_follow_topics_where_mentioned:
|
|
type: boolean
|
|
description: |
|
|
Whether the server will automatically mark the user as following
|
|
topics where the user is mentioned.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 235).
|
|
presence_enabled:
|
|
type: boolean
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
enter_sends:
|
|
type: boolean
|
|
description: |
|
|
Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys)
|
|
in the compose box is enabled.
|
|
enable_drafts_synchronization:
|
|
type: boolean
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
email_notifications_batching_period_seconds:
|
|
type: integer
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
available_notification_sounds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Array containing the names of the notification sound options
|
|
supported by this Zulip server. Only relevant to support UI
|
|
for configuring notification sounds.
|
|
emojiset_choices:
|
|
description: |
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
send_private_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
direct messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_stream_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
channel messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
allow_private_data_export:
|
|
type: boolean
|
|
description: |
|
|
Whether organization administrators are allowed to
|
|
export your private data.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 293).
|
|
email_address_visibility:
|
|
$ref: "#/components/schemas/EmailAddressVisibility"
|
|
web_navigate_to_sent_message:
|
|
type: boolean
|
|
description: |
|
|
Web/desktop app setting for whether the user's view should
|
|
automatically go to the conversation where they sent a message.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
|
|
this behavior was not configurable.
|
|
realm_users:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each entry describes a user
|
|
whose account has not been deactivated. Note that unlike
|
|
the usual User dictionary, this does not contain the `is_active`
|
|
key, as all the users present in this array have active accounts.
|
|
|
|
If the current user is a guest whose access to users is limited by a
|
|
`can_access_all_users_group` policy, and the event queue was registered
|
|
with the `user_list_incomplete` client capability, then users that the
|
|
current user cannot access will not be included in this array. If the
|
|
current user's access to a user is restricted but the client lacks this
|
|
capability, then that inaccessible user will appear in the users array as
|
|
an "Unknown user" object with the usual format but placeholder data whose
|
|
only variable content is the user ID.
|
|
|
|
See also `cross_realm_bots` and `realm_non_active_users`.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 232), the
|
|
`user_list_incomplete` client capability did not exist, and so all
|
|
clients whose access to a new user was prevented by
|
|
`can_access_all_users_group` policy would receive a fake "Unknown
|
|
user" event for such users.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
realm_non_active_users:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each entry describes a user
|
|
whose account has been deactivated. Note that unlike
|
|
the usual User dictionary this does not contain the `is_active`
|
|
key as all the users present in this array have deactivated
|
|
accounts.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
avatar_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The avatar data source type for the current user.
|
|
|
|
Value values are `G` (gravatar) and `U` (uploaded by user).
|
|
avatar_url_medium:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The avatar URL for the current user at 500x500 resolution, appropriate
|
|
for use in settings UI showing the user's avatar.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The URL of the avatar for the current user at 100x100
|
|
resolution. See also `avatar_url_medium`.
|
|
can_create_streams:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create at least one type
|
|
of channel with the organization's [channel creation
|
|
policy](/help/configure-who-can-create-channels). Its value will
|
|
always equal `can_create_public_streams || can_create_private_streams`.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 102), when
|
|
the new `create_private_stream_policy` and
|
|
`create_public_stream_policy` properties introduced the
|
|
possibility that a user could only create one type of channel.
|
|
|
|
This field will be removed in a future release.
|
|
can_create_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create public channels with
|
|
the organization's [channel creation policy](/help/configure-who-can-create-channels).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 102). In older
|
|
versions, the deprecated `can_create_streams` property should be
|
|
used to determine whether the user can create public channels.
|
|
can_create_private_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create private channels with
|
|
the organization's [channel creation policy](/help/configure-who-can-create-channels).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 102). In older
|
|
versions, the deprecated `can_create_streams` property should be
|
|
used to determine whether the user can create private channels.
|
|
can_create_web_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create public channels with
|
|
the organization's [channel creation policy](/help/configure-who-can-create-channels).
|
|
|
|
Note that this will be false if the Zulip server does not have the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has
|
|
not enabled the `enable_spectator_access` realm setting.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 103).
|
|
can_subscribe_other_users:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to subscribe other users to channels with
|
|
the organization's [channels policy](/help/configure-who-can-invite-to-channels).
|
|
can_invite_others_to_realm:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user [is allowed to invite others][who-can-send-invitations]
|
|
to the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 51).
|
|
|
|
[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization administrator](/api/roles-and-permissions).
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization owner](/api/roles-and-permissions).
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 11).
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
is_moderator:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization moderator](/api/roles-and-permissions).
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 60).
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is a [guest user](/api/roles-and-permissions).
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The unique ID for the current user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The Zulip API email address for the current user. See also
|
|
`delivery_email`; these may be the same or different depending
|
|
on the user's `email_address_visibility` policy.
|
|
delivery_email:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The user's email address, appropriate for UI for changing
|
|
the user's email address. See also `email`.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The full name of the current user.
|
|
cross_realm_bots:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Array of dictionaries where each dictionary contains details of
|
|
a single cross realm bot. Cross-realm bots are special system bot accounts
|
|
like Notification Bot.
|
|
|
|
Most clients will want to combine this with `realm_users` in many
|
|
contexts.
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/UserBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
delivery_email: {}
|
|
email: {}
|
|
full_name: {}
|
|
date_joined: {}
|
|
is_active: {}
|
|
is_owner: {}
|
|
is_admin: {}
|
|
is_guest: {}
|
|
is_billing_admin: {}
|
|
is_bot: {}
|
|
# Referenced schema properties are rendered before any
|
|
# non-referenced properties in the API documentation, so
|
|
# `is_system_bot` appears last instead of in this order.
|
|
# General practice should be to define properties in the
|
|
# same order that they are rendered in the API documentation.
|
|
# TODO: See if we can match the order of properties as
|
|
# listed here when rendered in the API documentation.
|
|
is_system_bot:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a system bot. System bots are special
|
|
bot user accounts that are managed by the system, rather than
|
|
the organization's administrators.
|
|
|
|
**Changes**: This field was called `is_cross_realm_bot`
|
|
before Zulip 5.0 (feature level 83).
|
|
bot_type:
|
|
nullable: true
|
|
bot_owner_id:
|
|
nullable: true
|
|
role: {}
|
|
timezone: {}
|
|
avatar_url:
|
|
nullable: true
|
|
avatar_version: {}
|
|
profile_data: {}
|
|
server_supported_permission_settings:
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Metadata detailing the valid values for permission settings that
|
|
use [group-setting values](/api/group-setting-values). Clients
|
|
should use these data as explained in the
|
|
[main documentation](/api/group-setting-values#permitted-values)
|
|
to determine what values to present as possible values for these
|
|
settings in UI components.
|
|
|
|
This part of the Zulip API is unstable and may change
|
|
significantly in future versions.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 221).
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
realm:
|
|
type: object
|
|
description: |
|
|
Configuration for realm level group permission settings.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/GroupPermissionSetting"
|
|
stream:
|
|
type: object
|
|
description: |
|
|
Configuration for channel level group permission settings.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/GroupPermissionSetting"
|
|
group:
|
|
type: object
|
|
description: |
|
|
Configuration for group level group permission settings.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/GroupPermissionSetting"
|
|
example:
|
|
{
|
|
"last_event_id": -1,
|
|
"msg": "",
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"realm_emoji":
|
|
{
|
|
"1":
|
|
{
|
|
"author_id": 5,
|
|
"deactivated": false,
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/1/emoji/images/1.png",
|
|
},
|
|
"2":
|
|
{
|
|
"author_id": 3,
|
|
"deactivated": false,
|
|
"id": "2",
|
|
"name": "animated_img",
|
|
"source_url": "/user_avatars/1/emoji/images/animated_img.gif",
|
|
"still_url": "/user_avatars/1/emoji/images/still/animated_img.png",
|
|
},
|
|
},
|
|
"result": "success",
|
|
"zulip_feature_level": 2,
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
}
|
|
/server_settings:
|
|
get:
|
|
operationId: get-server-settings
|
|
summary: Get server settings
|
|
tags: ["server_and_organizations"]
|
|
x-response-description: |
|
|
Please note that not all of these attributes are guaranteed to appear in a
|
|
response, for two reasons:
|
|
|
|
* This endpoint has evolved over time, so responses from older Zulip servers
|
|
might be missing some keys (in which case a client should assume the
|
|
appropriate default).
|
|
* If a `/server_settings` request is made to the root domain of a
|
|
multi-subdomain server, like the root domain of zulip.com, the settings
|
|
that are realm-specific are not known and thus not provided.
|
|
description: |
|
|
Fetch global settings for a Zulip server.
|
|
|
|
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
|
|
|
|
- If this is a Zulip server, and if so, what version of Zulip it's running.
|
|
- What a Zulip client (e.g. a mobile app or
|
|
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
|
|
know in order to display a login prompt for the server (e.g. what
|
|
authentication methods are available).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
authentication_methods:
|
|
type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Each key-value pair in the object indicates whether the authentication
|
|
method is enabled on this server.
|
|
|
|
**Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive
|
|
`external_authentication_methods`.
|
|
properties:
|
|
password:
|
|
description: |
|
|
Whether the user can authenticate using password.
|
|
type: boolean
|
|
dev:
|
|
description: |
|
|
Whether the user can authenticate using development API key.
|
|
type: boolean
|
|
email:
|
|
description: |
|
|
Whether the user can authenticate using email.
|
|
type: boolean
|
|
ldap:
|
|
description: |
|
|
Whether the user can authenticate using LDAP.
|
|
type: boolean
|
|
remoteuser:
|
|
description: |
|
|
Whether the user can authenticate using REMOTE_USER.
|
|
type: boolean
|
|
github:
|
|
description: |
|
|
Whether the user can authenticate using their GitHub account.
|
|
type: boolean
|
|
azuread:
|
|
description: |
|
|
Whether the user can authenticate using their Azure Active Directory account.
|
|
type: boolean
|
|
gitlab:
|
|
description: |
|
|
Whether the user can authenticate using their GitLab account.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
type: boolean
|
|
apple:
|
|
description: |
|
|
Whether the user can authenticate using their Apple account.
|
|
type: boolean
|
|
google:
|
|
description: |
|
|
Whether the user can authenticate using their Google account.
|
|
type: boolean
|
|
saml:
|
|
description: |
|
|
Whether the user can authenticate using SAML.
|
|
type: boolean
|
|
openid connect:
|
|
description: |
|
|
Whether the user can authenticate using OpenID Connect.
|
|
type: boolean
|
|
external_authentication_methods:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries describing the available external
|
|
authentication methods (E.g. Google, GitHub, or SAML)
|
|
enabled for this organization.
|
|
|
|
The list is sorted in the order in which these
|
|
authentication methods should be displayed.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
A unique, table, machine-readable name for the authentication method,
|
|
intended to be used by clients with special behavior for specific
|
|
authentication methods to correctly identify the method.
|
|
display_name:
|
|
type: string
|
|
description: |
|
|
Display name of the authentication method, to be used in all buttons
|
|
for the authentication method.
|
|
display_icon:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
URL for an image to be displayed as an icon in all buttons for
|
|
the external authentication method.
|
|
|
|
When `null`, no icon should be displayed.
|
|
login_url:
|
|
type: string
|
|
description: |
|
|
URL to be used to initiate authentication using this method.
|
|
signup_url:
|
|
type: string
|
|
description: |
|
|
URL to be used to initiate account registration using this method.
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
An integer indicating what features are
|
|
available on the server. The feature level increases monotonically;
|
|
a value of N means the server supports all API features introduced
|
|
before feature level N. This is designed to provide a simple way
|
|
for client apps to decide whether the server supports a given
|
|
feature or API change. See the [changelog](/api/changelog) for
|
|
details on what each feature level means.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1). We recommend using an
|
|
implied value of 0 for Zulip servers that do not send this field.
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The server's version number. This is often a release version number,
|
|
like `2.1.7`. But for a server running a [version from Git][git-release],
|
|
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
|
|
|
|
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The `git merge-base` between `zulip_version` and official branches
|
|
in the public
|
|
[Zulip server and web app repository](https://github.com/zulip/zulip),
|
|
in the same format as `zulip_version`. This will equal
|
|
`zulip_version` if the server is not running a fork of the Zulip server.
|
|
|
|
This will be `""` if unavailable.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether mobile/push notifications are configured.
|
|
is_incompatible:
|
|
type: boolean
|
|
description: |
|
|
Whether the Zulip client that has sent a request to this endpoint is
|
|
deemed incompatible with the server.
|
|
email_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Setting for allowing users authenticate with an email-password
|
|
combination.
|
|
require_email_format_usernames:
|
|
type: boolean
|
|
description: |
|
|
Whether all valid usernames for authentication to this
|
|
organization will be email addresses. This is important
|
|
for clients to know whether to do client side validation
|
|
of email address format in a login prompt.
|
|
|
|
This value will be false if the server has [LDAP
|
|
authentication][ldap-auth] enabled with a username and
|
|
password combination.
|
|
|
|
[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory
|
|
realm_uri:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The organization's canonical URL. Alias of `realm_url`.
|
|
|
|
**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term
|
|
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
|
|
realm_url:
|
|
type: string
|
|
description: |
|
|
The organization's canonical URL.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 257), replacing the
|
|
deprecated `realm_uri`.
|
|
realm_name:
|
|
type: string
|
|
description: |
|
|
The organization's name (for display purposes).
|
|
realm_icon:
|
|
type: string
|
|
description: |
|
|
The URL for the organization's logo formatted as a square image,
|
|
used for identifying the organization in small locations in the
|
|
mobile and desktop apps.
|
|
realm_description:
|
|
type: string
|
|
description: |
|
|
HTML description of the organization, as configured by the [organization
|
|
profile](/help/create-your-organization-profile).
|
|
realm_web_public_access_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has enabled the creation of
|
|
[web-public channels](/help/public-access-option) and
|
|
at least one web-public channel on the server currently
|
|
exists. Clients that support viewing content
|
|
in web-public channels without an account can
|
|
use this to determine whether to offer that
|
|
feature on the login page for an organization.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 116).
|
|
example:
|
|
{
|
|
"authentication_methods":
|
|
{
|
|
"password": true,
|
|
"dev": true,
|
|
"email": true,
|
|
"ldap": false,
|
|
"remoteuser": false,
|
|
"github": true,
|
|
"azuread": false,
|
|
"google": true,
|
|
"saml": true,
|
|
},
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
"push_notifications_enabled": false,
|
|
"msg": "",
|
|
"is_incompatible": false,
|
|
"email_auth_enabled": true,
|
|
"require_email_format_usernames": true,
|
|
"realm_uri": "http://localhost:9991",
|
|
"realm_url": "http://localhost:9991",
|
|
"realm_name": "Zulip Dev",
|
|
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
|
|
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
|
|
"realm_web_public_access_enabled": false,
|
|
"result": "success",
|
|
"external_authentication_methods":
|
|
[
|
|
{
|
|
"name": "saml:idp_name",
|
|
"display_name": "SAML",
|
|
"display_icon": null,
|
|
"login_url": "/accounts/login/social/saml/idp_name",
|
|
"signup_url": "/accounts/register/social/saml/idp_name",
|
|
},
|
|
{
|
|
"name": "google",
|
|
"display_name": "Google",
|
|
"display_icon": "/static/images/authentication_backends/googl_e-icon.png",
|
|
"login_url": "/accounts/login/social/google",
|
|
"signup_url": "/accounts/register/social/google",
|
|
},
|
|
{
|
|
"name": "github",
|
|
"display_name": "GitHub",
|
|
"display_icon": "/static/images/authentication_backends/github-icon.png",
|
|
"login_url": "/accounts/login/social/github",
|
|
"signup_url": "/accounts/register/social/github",
|
|
},
|
|
],
|
|
}
|
|
/settings:
|
|
patch:
|
|
operationId: update-settings
|
|
summary: Update settings
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint is used to edit the current user's settings.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 80), this
|
|
endpoint only supported the `full_name`, `email`,
|
|
`old_password`, and `new_password` parameters. Notification
|
|
settings were managed by `PATCH /settings/notifications`, and
|
|
all other settings by `PATCH /settings/display`.
|
|
|
|
The feature level 80 migration to merge these endpoints did not
|
|
change how request parameters are encoded. However, it did change
|
|
the handling of any invalid parameters present in a request
|
|
(see feature level 78 change below).
|
|
|
|
As of feature level 80, the `PATCH /settings/display` and
|
|
`PATCH /settings/notifications` endpoints are deprecated aliases
|
|
for this endpoint for backwards-compatibility, and will be removed
|
|
once clients have migrated to use this endpoint.
|
|
|
|
Prior to Zulip 5.0 (feature level 78), this endpoint indicated
|
|
which parameters it had processed by including in the response
|
|
object `"key": value` entries for values successfully changed by
|
|
the request. That was replaced by the more ergonomic
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array.
|
|
|
|
The `PATCH /settings/notifications` and `PATCH /settings/display`
|
|
endpoints also had this behavior of indicating processed parameters
|
|
before they became aliases of this endpoint in Zulip 5.0 (see
|
|
feature level 80 change above).
|
|
|
|
Before feature level 78, request parameters that were not supported
|
|
(or were unchanged) were silently ignored.
|
|
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- left_side_userlist
|
|
- emojiset
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
full_name:
|
|
description: |
|
|
A new display name for the user.
|
|
type: string
|
|
example: NewName
|
|
email:
|
|
description: |
|
|
Asks the server to initiate a confirmation sequence to change the user's email
|
|
address to the indicated value. The user will need to demonstrate control of the
|
|
new email address by clicking a confirmation link sent to that address.
|
|
type: string
|
|
example: newname@example.com
|
|
old_password:
|
|
description: |
|
|
The user's old Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
|
|
Required only when sending the `new_password` parameter.
|
|
type: string
|
|
example: old12345
|
|
new_password:
|
|
description: |
|
|
The user's new Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
|
|
The `old_password` parameter must be included in the request.
|
|
type: string
|
|
example: new12345
|
|
twenty_four_hour_time:
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
dense_mode:
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
web_mark_read_on_scroll_policy:
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
web_channel_default_view:
|
|
description: |
|
|
Web/desktop app setting controlling the default navigation
|
|
behavior when clicking on a channel link.
|
|
|
|
- 1 - Top topic in the channel
|
|
- 2 - Channel feed
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
|
|
was not configurable, and every user had the "Channel feed" behavior.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
example: 1
|
|
starred_message_counts:
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
receives_typing_notifications:
|
|
description: |
|
|
Whether the user is configured to receive typing notifications from other users.
|
|
The server will only deliver typing notifications events to users who for whom this
|
|
is enabled.
|
|
|
|
By default, this is set to true, enabling user to receive typing
|
|
notifications from other users.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only
|
|
options to disable sending typing notifications.
|
|
type: boolean
|
|
example: true
|
|
fluid_layout_width:
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
high_contrast_mode:
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
web_font_size_px:
|
|
description: |
|
|
User-configured primary `font-size` for the web application, in pixels.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
|
|
only adjustable via browser zoom. Note that this setting was not fully
|
|
implemented at this feature level.
|
|
type: integer
|
|
example: 14
|
|
web_line_height_percent:
|
|
description: |
|
|
User-configured primary `line-height` for the web application, in percent, so a
|
|
value of 120 represents a `line-height` of 1.2.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
|
|
not user-configurable. Note that this setting was not fully implemented at this
|
|
feature level.
|
|
type: integer
|
|
example: 122
|
|
color_scheme:
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
enable_drafts_synchronization:
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 87).
|
|
type: boolean
|
|
example: true
|
|
translate_emoticons:
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
display_emoji_reaction_users:
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting users, rather than
|
|
a count, for messages with few total reactions. The ideal cutoff may depend on
|
|
the space available for displaying reactions; the official web application
|
|
displays names when 3 or fewer total reactions are present with this setting
|
|
enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
type: boolean
|
|
example: false
|
|
default_language:
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
|
|
type: string
|
|
example: en
|
|
web_home_view:
|
|
description: |
|
|
The [home view](/help/configure-home-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "inbox" - Inbox view
|
|
- "all_messages" - Combined feed view
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
|
|
called `default_view`, which was new in Zulip 4.0 (feature level 42).
|
|
|
|
Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
type: string
|
|
example: all_messages
|
|
web_escape_navigates_to_home_view:
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured home view](/help/configure-home-view).
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
|
|
was called `escape_navigates_to_default_view`, which was new in Zulip
|
|
5.0 (feature level 107).
|
|
type: boolean
|
|
example: true
|
|
left_side_userlist:
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: boolean
|
|
example: true
|
|
emojiset:
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
type: string
|
|
example: "google"
|
|
demote_inactive_streams:
|
|
description: |
|
|
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
user_list_style:
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
web_animate_image_previews:
|
|
description: |
|
|
Controls how animated images should be played in the message feed in the web/desktop application.
|
|
|
|
- "always" - Always play the animated images in the message feed.
|
|
- "on_hover" - Play the animated images on hover over them in the message feed.
|
|
- "never" - Never play animated images in the message feed.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 275).
|
|
type: string
|
|
enum:
|
|
- always
|
|
- on_hover
|
|
- never
|
|
example: on_hover
|
|
web_stream_unreads_count_display_policy:
|
|
description: |
|
|
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
|
|
Channels that do not have an unread count will have a simple dot indicator for whether there are any
|
|
unread messages.
|
|
|
|
- 1 - All channels
|
|
- 2 - Unmuted channels and topics
|
|
- 3 - No channels
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 210).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 2
|
|
timezone:
|
|
description: |
|
|
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
type: string
|
|
example: "Asia/Kolkata"
|
|
enable_stream_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for channel messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_email_notifications:
|
|
description: |
|
|
Enable email notifications for channel messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_push_notifications:
|
|
description: |
|
|
Enable mobile notifications for channel messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_stream_audible_notifications:
|
|
description: |
|
|
Enable audible desktop notifications for channel messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
notification_sound:
|
|
description: |
|
|
Notification sound name.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
|
|
type: string
|
|
example: ding
|
|
enable_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for direct messages and @-mentions.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_sounds:
|
|
description: |
|
|
Enable audible desktop notifications for direct messages and
|
|
@-mentions.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
email_notifications_batching_period_seconds:
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 82)
|
|
type: integer
|
|
example: 120
|
|
enable_offline_email_notifications:
|
|
description: |
|
|
Enable email notifications for direct messages and @-mentions received
|
|
when the user is offline.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_offline_push_notifications:
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is offline.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_online_push_notifications:
|
|
description: |
|
|
Enable mobile notification for direct messages and @-mentions received
|
|
when the user is online.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_desktop_notifications:
|
|
description: |
|
|
Enable visual desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_email_notifications:
|
|
description: |
|
|
Enable email notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_push_notifications:
|
|
description: |
|
|
Enable push notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: false
|
|
enable_followed_topic_audible_notifications:
|
|
description: |
|
|
Enable audible desktop notifications for messages sent to followed topics.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: false
|
|
enable_digest_emails:
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_marketing_emails:
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_login_emails:
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
message_content_in_email_notifications:
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
pm_content_in_desktop_notifications:
|
|
description: |
|
|
Include content of direct messages in desktop notifications.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
wildcard_mentions_notify:
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
description: |
|
|
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
|
|
should send notifications like a personal mention.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 189).
|
|
type: boolean
|
|
example: true
|
|
desktop_icon_count_display:
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unread messages
|
|
- 2 - DMs, mentions, and followed topics
|
|
- 3 - DMs and mentions
|
|
- 4 - None
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed
|
|
topics` option, renumbering the options to insert it in order.
|
|
|
|
Before Zulip 5.0 (feature level 80), this setting was managed by the
|
|
`PATCH /settings/notifications` endpoint.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
realm_name_in_email_notifications_policy:
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
|
|
Before Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications`
|
|
setting was managed by the `PATCH /settings/notifications` endpoint.
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
automatically_follow_topics_policy:
|
|
description: |
|
|
Which [topics to follow automatically](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
description: |
|
|
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
|
|
|
|
- 1 - Topics the user participates in
|
|
- 2 - Topics the user sends a message to
|
|
- 3 - Topics the user starts
|
|
- 4 - Never
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 214).
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
example: 1
|
|
automatically_follow_topics_where_mentioned:
|
|
description: |
|
|
Whether the server will automatically mark the user as following
|
|
topics where the user is mentioned.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 235).
|
|
type: boolean
|
|
example: true
|
|
presence_enabled:
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
type: boolean
|
|
example: true
|
|
enter_sends:
|
|
description: |
|
|
Whether pressing Enter in the compose box sends a message
|
|
(or saves a message edit).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by
|
|
the `POST /users/me/enter-sends` endpoint, with the same parameter format.
|
|
type: boolean
|
|
example: true
|
|
send_private_typing_notifications:
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
direct messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
send_stream_typing_notifications:
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
channel messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
send_read_receipts:
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
type: boolean
|
|
example: true
|
|
allow_private_data_export:
|
|
description: |
|
|
Whether organization administrators are allowed to
|
|
export your private data.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 293).
|
|
type: boolean
|
|
example: true
|
|
email_address_visibility:
|
|
description: |
|
|
The [policy][permission-level] this user has selected for [which other
|
|
users][help-email-visibility] in this organization can see their real
|
|
email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
- 5
|
|
example: 1
|
|
web_navigate_to_sent_message:
|
|
description: |
|
|
Web/desktop app setting for whether the user's view should
|
|
automatically go to the conversation where they sent a message.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
|
|
this behavior was not configurable.
|
|
type: boolean
|
|
example: true
|
|
encoding:
|
|
twenty_four_hour_time:
|
|
contentType: application/json
|
|
dense_mode:
|
|
contentType: application/json
|
|
web_mark_read_on_scroll_policy:
|
|
contentType: application/json
|
|
web_channel_default_view:
|
|
contentType: application/json
|
|
starred_message_counts:
|
|
contentType: application/json
|
|
receives_typing_notifications:
|
|
contentType: application/json
|
|
fluid_layout_width:
|
|
contentType: application/json
|
|
high_contrast_mode:
|
|
contentType: application/json
|
|
web_font_size_px:
|
|
contentType: application/json
|
|
web_line_height_percent:
|
|
contentType: application/json
|
|
color_scheme:
|
|
contentType: application/json
|
|
enable_drafts_synchronization:
|
|
contentType: application/json
|
|
translate_emoticons:
|
|
contentType: application/json
|
|
display_emoji_reaction_users:
|
|
contentType: application/json
|
|
web_escape_navigates_to_home_view:
|
|
contentType: application/json
|
|
left_side_userlist:
|
|
contentType: application/json
|
|
demote_inactive_streams:
|
|
contentType: application/json
|
|
user_list_style:
|
|
contentType: application/json
|
|
web_stream_unreads_count_display_policy:
|
|
contentType: application/json
|
|
enable_stream_desktop_notifications:
|
|
contentType: application/json
|
|
enable_stream_email_notifications:
|
|
contentType: application/json
|
|
enable_stream_push_notifications:
|
|
contentType: application/json
|
|
enable_stream_audible_notifications:
|
|
contentType: application/json
|
|
enable_desktop_notifications:
|
|
contentType: application/json
|
|
enable_sounds:
|
|
contentType: application/json
|
|
email_notifications_batching_period_seconds:
|
|
contentType: application/json
|
|
enable_offline_email_notifications:
|
|
contentType: application/json
|
|
enable_offline_push_notifications:
|
|
contentType: application/json
|
|
enable_online_push_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_desktop_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_email_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_push_notifications:
|
|
contentType: application/json
|
|
enable_followed_topic_audible_notifications:
|
|
contentType: application/json
|
|
enable_digest_emails:
|
|
contentType: application/json
|
|
enable_marketing_emails:
|
|
contentType: application/json
|
|
enable_login_emails:
|
|
contentType: application/json
|
|
message_content_in_email_notifications:
|
|
contentType: application/json
|
|
pm_content_in_desktop_notifications:
|
|
contentType: application/json
|
|
wildcard_mentions_notify:
|
|
contentType: application/json
|
|
enable_followed_topic_wildcard_mentions_notify:
|
|
contentType: application/json
|
|
desktop_icon_count_display:
|
|
contentType: application/json
|
|
realm_name_in_email_notifications_policy:
|
|
contentType: application/json
|
|
automatically_follow_topics_policy:
|
|
contentType: application/json
|
|
automatically_unmute_topics_in_muted_streams_policy:
|
|
contentType: application/json
|
|
automatically_follow_topics_where_mentioned:
|
|
contentType: application/json
|
|
presence_enabled:
|
|
contentType: application/json
|
|
enter_sends:
|
|
contentType: application/json
|
|
send_private_typing_notifications:
|
|
contentType: application/json
|
|
send_stream_typing_notifications:
|
|
contentType: application/json
|
|
send_read_receipts:
|
|
contentType: application/json
|
|
allow_private_data_export:
|
|
contentType: application/json
|
|
email_address_visibility:
|
|
contentType: application/json
|
|
web_navigate_to_sent_message:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
/streams/{stream_id}/members:
|
|
get:
|
|
operationId: get-subscribers
|
|
summary: Get channel subscribers
|
|
tags: ["channels"]
|
|
description: |
|
|
Get all users subscribed to a channel.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the IDs of all active users who are subscribed
|
|
to the channel.
|
|
example:
|
|
{"result": "success", "msg": "", "subscribers": [11, 26]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the requested channel does not exist,
|
|
or where the user does not have permission to access the target channel:
|
|
/streams:
|
|
get:
|
|
operationId: get-streams
|
|
summary: Get all channels
|
|
tags: ["channels"]
|
|
description: |
|
|
Get all channels that the user [has access to](/help/channel-permissions).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- include_public
|
|
description: |
|
|
You may pass in one or more of the parameters mentioned below
|
|
as URL query parameters, like so:
|
|
parameters:
|
|
- name: include_public
|
|
in: query
|
|
description: |
|
|
Include all public channels.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: include_web_public
|
|
in: query
|
|
description: |
|
|
Include all web-public channels.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_subscribed
|
|
in: query
|
|
description: |
|
|
Include all channels that the user is subscribed to.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: exclude_archived
|
|
in: query
|
|
description: |
|
|
Whether to exclude archived streams from the results.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 315).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: true
|
|
- name: include_all_active
|
|
in: query
|
|
description: |
|
|
Include all active channels. The user must have administrative privileges
|
|
to use this parameter.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_default
|
|
in: query
|
|
description: |
|
|
Include all default channels for the user's realm.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_owner_subscribed
|
|
in: query
|
|
description: |
|
|
If the user is a bot, include all channels that the bot's owner is
|
|
subscribed to.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
streams:
|
|
description: |
|
|
A list of channel objects with details on the requested channels.
|
|
type: array
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicChannelBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
is_archived: {}
|
|
description: {}
|
|
date_created: {}
|
|
creator_id:
|
|
nullable: true
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group: {}
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the channel per week, as
|
|
estimated based on recent weeks, rounded to the nearest integer.
|
|
|
|
If `null`, no information is provided on the average traffic.
|
|
This can be because the channel was recently created and there
|
|
is insufficient data to make an estimate, or because the server
|
|
wishes to omit this information for this client, this realm, or
|
|
this endpoint or type of event.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 199). Previously,
|
|
this statistic was available only in subscription objects.
|
|
is_default:
|
|
type: boolean
|
|
description: |
|
|
Only present when [`include_default`][include_default]
|
|
parameter is `true`.
|
|
|
|
Whether the given channel is a
|
|
[default channel](/help/set-default-channels-for-new-users).
|
|
|
|
[include_default]: /api/get-streams#parameter-include_default
|
|
required:
|
|
- stream_id
|
|
- name
|
|
- is_archived
|
|
- description
|
|
- date_created
|
|
- creator_id
|
|
- invite_only
|
|
- rendered_description
|
|
- is_web_public
|
|
- stream_post_policy
|
|
- message_retention_days
|
|
- history_public_to_subscribers
|
|
- first_message_id
|
|
- is_announcement_only
|
|
- can_remove_subscribers_group
|
|
- stream_weekly_traffic
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"streams":
|
|
[
|
|
{
|
|
"can_remove_subscribers_group": 10,
|
|
"creator_id": null,
|
|
"date_created": 1691057093,
|
|
"description": "A private channel",
|
|
"first_message_id": 18,
|
|
"history_public_to_subscribers": false,
|
|
"invite_only": true,
|
|
"is_announcement_only": false,
|
|
"is_archived": false,
|
|
"is_default": false,
|
|
"is_web_public": false,
|
|
"message_retention_days": null,
|
|
"name": "management",
|
|
"rendered_description": "<p>A private channel</p>",
|
|
"stream_id": 2,
|
|
"stream_post_policy": 1,
|
|
"stream_weekly_traffic": null,
|
|
},
|
|
{
|
|
"can_remove_subscribers_group": 9,
|
|
"creator_id": 12,
|
|
"date_created": 1691057093,
|
|
"description": "A default public channel",
|
|
"first_message_id": 21,
|
|
"history_public_to_subscribers": true,
|
|
"invite_only": false,
|
|
"is_announcement_only": false,
|
|
"is_archived": false,
|
|
"is_default": true,
|
|
"is_web_public": false,
|
|
"message_retention_days": null,
|
|
"name": "welcome",
|
|
"rendered_description": "<p>A default public channel</p>",
|
|
"stream_id": 1,
|
|
"stream_post_policy": 1,
|
|
"stream_weekly_traffic": null,
|
|
},
|
|
],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User not authorized for this query",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is not authorized to use the
|
|
`include_all_active` parameter (i.e. because they are not an organization
|
|
administrator):
|
|
/streams/{stream_id}:
|
|
get:
|
|
operationId: get-stream-by-id
|
|
summary: Get a channel by ID
|
|
tags: ["channels"]
|
|
description: |
|
|
Fetch details for the channel with the ID `stream_id`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 132).
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
stream:
|
|
$ref: "#/components/schemas/BasicChannel"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"stream":
|
|
{
|
|
"description": "A Scandinavian country",
|
|
"first_message_id": 1,
|
|
"history_public_to_subscribers": true,
|
|
"date_created": 1691057093,
|
|
"creator_id": null,
|
|
"invite_only": false,
|
|
"is_announcement_only": false,
|
|
"is_archived": false,
|
|
"is_web_public": false,
|
|
"message_retention_days": null,
|
|
"name": "Denmark",
|
|
"rendered_description": "<p>A Scandinavian country</p>",
|
|
"stream_id": 7,
|
|
"stream_post_policy": 1,
|
|
"can_remove_subscribers_group": 2,
|
|
"stream_weekly_traffic": null,
|
|
},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the channel ID is not valid:
|
|
delete:
|
|
operationId: archive-stream
|
|
summary: Archive a channel
|
|
tags: ["channels"]
|
|
description: |
|
|
[Archive the channel](/help/archive-a-channel) with the ID `stream_id`.
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the supplied channel does not exist:
|
|
patch:
|
|
operationId: update-stream
|
|
summary: Update a channel
|
|
tags: ["channels"]
|
|
description: |
|
|
Configure the channel with the ID `stream_id`. This endpoint supports
|
|
an organization administrator editing any property of a channel,
|
|
including:
|
|
|
|
- Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description)
|
|
- Channel [permissions](/help/channel-permissions), including
|
|
[privacy](/help/change-the-privacy-of-a-channel) and [who can
|
|
send](/help/channel-posting-policy).
|
|
|
|
Note that an organization administrator's ability to change a
|
|
[private channel's permissions](/help/channel-permissions#private-channels)
|
|
depends on them being subscribed to the channel.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- new_name
|
|
- description
|
|
- is_private
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
description:
|
|
description: |
|
|
The new [description](/help/change-the-channel-description) for
|
|
the channel, in text/markdown format.
|
|
|
|
Clients should use the `max_stream_description_length` returned
|
|
by the [`POST /register`](/api/register-queue) endpoint to
|
|
determine the maximum channel description length.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 4.0 (feature level 64).
|
|
type: string
|
|
example: "Discuss Italian history and travel destinations."
|
|
new_name:
|
|
description: |
|
|
The new name for the channel.
|
|
|
|
Clients should use the `max_stream_name_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum channel name length.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 4.0 (feature level 64).
|
|
type: string
|
|
example: Italy
|
|
is_private:
|
|
description: |
|
|
Change whether the channel is a private channel.
|
|
type: boolean
|
|
example: true
|
|
is_announcement_only:
|
|
deprecated: true
|
|
description: |
|
|
Whether the channel is limited to announcements.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
type: boolean
|
|
example: true
|
|
is_web_public:
|
|
description: |
|
|
Change whether the channel is a web-public channel.
|
|
|
|
Note that creating web-public channels requires the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
|
|
to be enabled on the Zulip server in question, the organization
|
|
to have enabled the `enable_spectator_access` realm setting, and
|
|
the current use to have permission under the organization's
|
|
`can_create_web_public_channel_group` realm setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 98).
|
|
type: boolean
|
|
example: true
|
|
history_public_to_subscribers:
|
|
description: |
|
|
Whether the channel's message history should be available to
|
|
newly subscribed members, or users can only access messages
|
|
they actually received while subscribed to the channel.
|
|
|
|
Corresponds to the [shared history](/help/channel-permissions)
|
|
option in documentation.
|
|
|
|
It's an error for this parameter to be false for a public or
|
|
web-public channel and when is_private is false.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers`
|
|
was silently ignored unless the request also contained either `is_private` or
|
|
`is_web_public`.
|
|
type: boolean
|
|
example: false
|
|
is_default_stream:
|
|
description: |
|
|
Add or remove the channel as a [default channel][default-channel]
|
|
for new users joining the organization.
|
|
|
|
[default-channel]: /help/set-default-channels-for-new-users
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status
|
|
could only be changed using the [dedicated API endpoint](/api/add-default-stream).
|
|
type: boolean
|
|
example: false
|
|
stream_post_policy:
|
|
$ref: "#/components/schemas/ChannelPostPolicy"
|
|
message_retention_days:
|
|
$ref: "#/components/schemas/MessageRetentionDays"
|
|
can_remove_subscribers_group:
|
|
description: |
|
|
The set of users who have permission to unsubscribe others from this
|
|
channel expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
Note that a user who is a member of the specified user group must
|
|
also [have access](/help/channel-permissions) to the channel in
|
|
order to unsubscribe others.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 320), this value was
|
|
always the integer ID of a system group.
|
|
|
|
Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`
|
|
setting was named `can_remove_subscribers_group_id`.
|
|
|
|
New in Zulip 7.0 (feature level 161).
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for who would
|
|
have the permission to remove subscribers from the channel.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for who has the permission to remove subscribers from the channel.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 15,
|
|
}
|
|
encoding:
|
|
is_private:
|
|
contentType: application/json
|
|
is_announcement_only:
|
|
contentType: application/json
|
|
is_web_public:
|
|
contentType: application/json
|
|
history_public_to_subscribers:
|
|
contentType: application/json
|
|
is_default_stream:
|
|
contentType: application/json
|
|
stream_post_policy:
|
|
contentType: application/json
|
|
can_remove_subscribers_group:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the supplied channel does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid parameters",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when invalid combination of channel permission
|
|
parameters are passed:
|
|
/streams/{stream_id}/email_address:
|
|
get:
|
|
operationId: get-stream-email-address
|
|
summary: Get channel's email address
|
|
tags: ["channels"]
|
|
description: |
|
|
Get email address of a channel.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 226).
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
email:
|
|
type: string
|
|
description: |
|
|
Email address of the channel.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"email": "test.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidChannelError"
|
|
- description: |
|
|
An example JSON response for when the requested channel does not exist,
|
|
or where the user does not have permission to access the target channel:
|
|
/streams/{stream_id}/delete_topic:
|
|
post:
|
|
operationId: delete-topic
|
|
summary: Delete a topic
|
|
tags: ["channels"]
|
|
description: |
|
|
Delete all messages in a topic.
|
|
|
|
Topics are a field on messages (not an independent data structure), so
|
|
deleting all the messages in the topic deletes the topic from Zulip.
|
|
|
|
Because this endpoint deletes messages in batches, it is possible for
|
|
the request to time out after only deleting some messages in the topic.
|
|
When this happens, the `complete` boolean field in the success response
|
|
will be `false`. Clients should repeat the request when handling such a
|
|
response. If all messages in the topic were deleted, then the success
|
|
response will return `"complete": true`.
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 256), the server never sent
|
|
[`stream` op: `update`](/api/get-events#stream-update) events with an
|
|
updated `first_message_id` for a channel when the oldest message that
|
|
had been sent to it changed.
|
|
|
|
Before Zulip 8.0 (feature level 211), if the server's
|
|
processing was interrupted by a timeout, but some messages in the topic
|
|
were deleted, then it would return `"result": "partially_completed"`,
|
|
along with a `code` field for an error string, in the success response
|
|
to indicate that there was a timeout and that the client should repeat
|
|
the request.
|
|
|
|
As of Zulip 6.0 (feature level 154), instead of returning an error
|
|
response when a request times out after successfully deleting some of
|
|
the messages in the topic, a success response is returned with
|
|
`"result": "partially_completed"` to indicate that some messages were
|
|
deleted.
|
|
|
|
Before Zulip 6.0 (feature level 147), this request did a single atomic
|
|
operation, which could time out for very large topics. As of this
|
|
feature level, messages are deleted in batches, starting with the newest
|
|
messages, so that progress is made even if the request times out and
|
|
returns an error.
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- $ref: "#/components/parameters/ChannelIdInPath"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
topic_name:
|
|
description: |
|
|
The name of the topic to delete.
|
|
type: string
|
|
example: new coffee machine
|
|
required:
|
|
- topic_name
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
required:
|
|
- complete
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
complete:
|
|
type: boolean
|
|
description: |
|
|
Whether all unread messages were marked as read.
|
|
|
|
Will be `false` if the request successfully marked
|
|
some, but not all, messages as read.
|
|
example: {"msg": "", "result": "success", "complete": true}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Must be an organization administrator",
|
|
"code": "UNAUTHORIZED_PRINCIPAL",
|
|
}
|
|
description: |
|
|
Error when the user does not have permission
|
|
to delete topics in this organization:
|
|
/typing:
|
|
post:
|
|
operationId: set-typing-status
|
|
summary: Set "typing" status
|
|
tags: ["users"]
|
|
description: |
|
|
Notify other users whether the current user is
|
|
[typing a message][help-typing].
|
|
|
|
Clients implementing Zulip's typing notifications
|
|
protocol should work as follows:
|
|
|
|
- Send a request to this endpoint with `"op": "start"` when a user
|
|
starts composing a message.
|
|
- While the user continues to actively type or otherwise interact with
|
|
the compose UI (e.g. interacting with the compose box emoji picker),
|
|
send regular `"op": "start"` requests to this endpoint, using
|
|
`server_typing_started_wait_period_milliseconds` in the
|
|
[`POST /register`][api-register] response as the time interval
|
|
between each request.
|
|
- Send a request to this endpoint with `"op": "stop"` when a user
|
|
has stopped using the compose UI for the time period indicated by
|
|
`server_typing_stopped_wait_period_milliseconds` in the
|
|
[`POST /register`][api-register] response or when a user
|
|
cancels the compose action (if it had previously sent a "start"
|
|
notification for that compose action).
|
|
- Start displaying a visual typing indicator for a given conversation
|
|
when a [`typing op:start`][start-typing] event is received
|
|
from the server.
|
|
- Continue displaying a visual typing indicator for the conversation
|
|
until a [`typing op:stop`][stop-typing] event is received
|
|
from the server or the time period indicated by
|
|
`server_typing_started_expiry_period_milliseconds` in the
|
|
[`POST /register`][api-register] response has passed without
|
|
a new `typing "op": "start"` event for the conversation.
|
|
|
|
This protocol is designed to allow the server-side typing notifications
|
|
implementation to be stateless while being resilient as network failures
|
|
will not result in a user being incorrectly displayed as perpetually
|
|
typing.
|
|
|
|
See the subsystems documentation on [typing indicators][typing-protocol-docs]
|
|
for additional design details on Zulip's typing notifications protocol.
|
|
|
|
**Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215)
|
|
for channel typing notifications, as no client actually implemented
|
|
the previous API for those.
|
|
|
|
Support for displaying channel typing notifications was new
|
|
in Zulip 4.0 (feature level 58). Clients should indicate they support
|
|
processing channel typing notifications via the `stream_typing_notifications`
|
|
value in the `client_capabilities` parameter of the
|
|
[`POST /register`][client-capabilities] endpoint.
|
|
|
|
[help-typing]: /help/typing-notifications
|
|
[api-register]: /api/register-queue
|
|
[start-typing]: /api/get-events#typing-start
|
|
[stop-typing]: /api/get-events#typing-stop
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
[typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- topic
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
description: |
|
|
Type of the message being composed.
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
|
|
an additional value for this parameter to indicate a channel message is
|
|
being composed.
|
|
|
|
In Zulip 8.0 (feature level 215), stopped supporting
|
|
`"private"` as a valid value for this parameter.
|
|
|
|
In Zulip 7.0 (feature level 174), `"direct"` was added
|
|
as the preferred way to indicate a direct message is being composed,
|
|
becoming the default value for this parameter and deprecating the
|
|
original `"private"`.
|
|
|
|
New in Zulip 4.0 (feature level 58). Previously, typing notifications
|
|
were only for direct messages.
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- stream
|
|
- channel
|
|
default: direct
|
|
example: direct
|
|
op:
|
|
description: |
|
|
Whether the user has started (`"start"`) or stopped (`"stop"`) typing.
|
|
type: string
|
|
enum:
|
|
- start
|
|
- stop
|
|
example: start
|
|
to:
|
|
description: |
|
|
User IDs of the recipients of the message being typed. Required for the
|
|
`"direct"` type. Ignored in the case of `"stream"` or `"channel"` type.
|
|
|
|
Clients should send a JSON-encoded list of user IDs, even if there is only
|
|
one recipient.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter
|
|
for the `"stream"` type. Previously, in the case of the `"stream"` type, it
|
|
accepted a single-element list containing the ID of the channel. A new parameter,
|
|
`stream_id`, is now used for this. Note that the `"channel"` type did not
|
|
exist at this feature level.
|
|
|
|
Support for typing notifications for channel' messages
|
|
is new in Zulip 4.0 (feature level 58). Previously, typing
|
|
notifications were only for direct messages.
|
|
|
|
Before Zulip 2.0.0, this parameter accepted only a JSON-encoded
|
|
list of email addresses. Support for the email address-based format was
|
|
removed in Zulip 3.0 (feature level 11).
|
|
type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: [9, 10]
|
|
stream_id:
|
|
description: |
|
|
ID of the channel in which the message is being typed. Required for the `"stream"`
|
|
or `"channel"` type. Ignored in the case of `"direct"` type.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element
|
|
list containing the ID of the channel was passed in `to` parameter.
|
|
type: integer
|
|
example: 7
|
|
topic:
|
|
description: |
|
|
Topic to which message is being typed. Required for the `"stream"` or `"channel"`
|
|
type. Ignored in the case of `"direct"` type.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously, typing
|
|
notifications were only for direct messages.
|
|
type: string
|
|
example: typing notifications
|
|
required:
|
|
- op
|
|
encoding:
|
|
to:
|
|
contentType: application/json
|
|
stream_id:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Missing channel ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response when the user composes a channel message
|
|
and `stream_id` is not specified:
|
|
/user_groups/create:
|
|
post:
|
|
operationId: create-user-group
|
|
summary: Create a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Create a new [user group](/help/user-groups).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: |
|
|
The name of the user group.
|
|
type: string
|
|
example: marketing
|
|
description:
|
|
description: |
|
|
The description of the user group.
|
|
type: string
|
|
example: The marketing team.
|
|
members:
|
|
description: |
|
|
An array containing the user IDs of the initial members for the
|
|
new user group.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 2, 3, 4]
|
|
subgroups:
|
|
description: |
|
|
An array containing the IDs of the initial subgroups for the new
|
|
user group.
|
|
|
|
User can add subgroups to the new group irrespective of other
|
|
permissions for the new group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 311).
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [11]
|
|
can_add_members_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to add members to this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 305). Previously, this
|
|
permission was controlled by the `can_manage_group` setting.
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
example: 11
|
|
can_join_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to join this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 301).
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
example: 11
|
|
can_leave_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to leave this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 308).
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
example: 15
|
|
can_manage_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [manage this user group][manage-user-groups].
|
|
|
|
This setting cannot be set to `"role:internet"` and `"role:everyone"`
|
|
[system groups][system-groups].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 283).
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[manage-user-groups]: /help/manage-user-groups
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
example: 11
|
|
can_mention_group:
|
|
allOf:
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [mention this user group][mentions].
|
|
|
|
This setting cannot be set to `"role:internet"` and `"role:owners"`
|
|
[system groups][system-groups].
|
|
|
|
Before Zulip 9.0 (feature level 258), this parameter could only be the
|
|
integer form of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 8.0 (feature level 198), this parameter was named
|
|
`can_mention_group_id`.
|
|
|
|
New in Zulip 8.0 (feature level 191). Previously, groups could be
|
|
mentioned only if they were not [system groups][system-groups].
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[mentions]: /help/mention-a-user-or-group
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
example: 11
|
|
required:
|
|
- name
|
|
- description
|
|
- members
|
|
encoding:
|
|
members:
|
|
contentType: application/json
|
|
subgroups:
|
|
contentType: application/json
|
|
can_add_members_group:
|
|
contentType: application/json
|
|
can_join_group:
|
|
contentType: application/json
|
|
can_leave_group:
|
|
contentType: application/json
|
|
can_manage_group:
|
|
contentType: application/json
|
|
can_mention_group:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: |
|
|
A success response containing the unique ID of the user group.
|
|
This field provides a straightforward way to reference the
|
|
newly created user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 317).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- required:
|
|
- group_id
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the created user group.
|
|
example: {"msg": "", "result": "success", "group_id": 123}
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user ID: 500",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the one of the users does not exist:
|
|
/user_groups/{user_group_id}/members:
|
|
post:
|
|
operationId: update-user-group-members
|
|
summary: Update user group members
|
|
tags: ["users"]
|
|
description: |
|
|
Update the members of a [user group](/help/user-groups). The
|
|
user IDs must correspond to non-deactivated users.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of
|
|
deactivated users were visible to the API and could be edited via this endpoint.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- delete
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
delete:
|
|
description: |
|
|
The list of user IDs to be removed from the user group.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [10]
|
|
add:
|
|
description: |
|
|
The list of user IDs to be added to the user group.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [12, 13]
|
|
delete_subgroups:
|
|
description: |
|
|
The list of user group IDs to be removed from the user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 311).
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [9]
|
|
add_subgroups:
|
|
description: |
|
|
The list of user group IDs to be added to the user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 311).
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [9]
|
|
encoding:
|
|
delete:
|
|
contentType: application/json
|
|
add:
|
|
contentType: application/json
|
|
delete_subgroups:
|
|
contentType: application/json
|
|
add_subgroups:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
get:
|
|
operationId: get-user-group-members
|
|
summary: Get user group members
|
|
tags: ["users"]
|
|
description: |
|
|
Get the members of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- $ref: "#/components/parameters/DirectMemberOnly"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
members:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the user IDs of members of the user group.
|
|
example:
|
|
{"msg": "", "result": "success", "members": [10, 12]}
|
|
/user_groups/{user_group_id}:
|
|
patch:
|
|
operationId: update-user-group
|
|
summary: Update a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Update the name or description of a [user group](/help/user-groups).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: |
|
|
The new name of the group.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 165), this was
|
|
a required field.
|
|
type: string
|
|
example: marketing team
|
|
description:
|
|
description: |
|
|
The new description of the group.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 165), this was
|
|
a required field.
|
|
type: string
|
|
example: The marketing team.
|
|
can_add_members_group:
|
|
description: |
|
|
The set of users who have permission to add members to this user group
|
|
expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 305). Previously, this
|
|
permission was controlled by the `can_manage_group` setting.
|
|
|
|
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for the set of users
|
|
who would have the permission to add members to the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for the set of users who have the permission to add members to the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 11,
|
|
}
|
|
can_join_group:
|
|
description: |
|
|
The set of users who have permission to join this user group
|
|
expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 301).
|
|
|
|
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for who would
|
|
have the permission to join the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for who has the permission to join the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 11,
|
|
}
|
|
can_leave_group:
|
|
description: |
|
|
The set of users who have permission to leave this user group
|
|
expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 308).
|
|
|
|
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for who would
|
|
have the permission to leave the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for who has the permission to leave the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 15,
|
|
}
|
|
can_manage_group:
|
|
description: |
|
|
The set of users who have permission to [manage this user group][manage-user-groups]
|
|
expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
This setting cannot be set to `"role:internet"` and `"role:everyone"`
|
|
[system groups][system-groups].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 283).
|
|
|
|
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[manage-user-groups]: /help/manage-user-groups
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for who would
|
|
have the permission to manage the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for who has the permission to manage the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 11,
|
|
}
|
|
can_mention_group:
|
|
description: |
|
|
The set of users who have permission to [mention this group][mentions],
|
|
expressed as an [update to a group-setting value][update-group-setting].
|
|
|
|
This setting cannot be set to `"role:internet"` and `"role:owners"`
|
|
[system groups][system-groups].
|
|
|
|
**Changes**: In Zulip 9.0 (feature level 260), this parameter was
|
|
updated to only accept an object with the `old` and `new` fields
|
|
described below. Prior to this feature level, this parameter could be
|
|
either of the two forms of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 9.0 (feature level 258), this parameter could only be the
|
|
integer form of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 8.0 (feature level 198), this parameter was named
|
|
`can_mention_group_id`.
|
|
|
|
New in Zulip 8.0 (feature level 191). Previously, groups could be
|
|
mentioned only if they were not [system groups][system-groups].
|
|
|
|
[mentions]: /help/mention-a-user-or-group
|
|
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[setting-values]: /api/group-setting-values
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
new:
|
|
allOf:
|
|
- description: |
|
|
The new [group-setting value](/api/group-setting-values) for who would
|
|
have the permission to mention the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
old:
|
|
allOf:
|
|
- description: |
|
|
The expected current [group-setting value](/api/group-setting-values)
|
|
for who has the permission to mention the group.
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
required:
|
|
- new
|
|
example:
|
|
{
|
|
"new": {"direct_members": [10], "direct_subgroups": [11]},
|
|
"old": 11,
|
|
}
|
|
encoding:
|
|
can_add_members_group:
|
|
contentType: application/json
|
|
can_join_group:
|
|
contentType: application/json
|
|
can_leave_group:
|
|
contentType: application/json
|
|
can_manage_group:
|
|
contentType: application/json
|
|
can_mention_group:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user group",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response when the user group ID is invalid:
|
|
/user_groups:
|
|
get:
|
|
operationId: get-user-groups
|
|
summary: Get user groups
|
|
tags: ["users"]
|
|
description: |
|
|
Fetches all of the user groups in the organization.
|
|
|
|
!!! warn ""
|
|
|
|
**Note**: This endpoint is only available to [members and
|
|
administrators](/help/roles-and-permissions); bots and guests
|
|
cannot use this endpoint.
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
include_deactivated_groups:
|
|
description: |
|
|
Whether to include deactivated user groups in the response.
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 294), renamed
|
|
`allow_deactivated` to `include_deactivated_groups`.
|
|
|
|
New in Zulip 10.0 (feature level 290). Previously, deactivated
|
|
user groups did not exist and thus would never be included in
|
|
the response.
|
|
type: boolean
|
|
example: true
|
|
default: false
|
|
encoding:
|
|
allow_deactivated:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_groups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
description:
|
|
type: string
|
|
description: |
|
|
The human-readable description of the user group.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The user group's integer ID.
|
|
date_created:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The UNIX timestamp for when the user group was created, in UTC seconds.
|
|
|
|
A `null` value means the user group has no recorded date, which is often
|
|
because the group predates the metadata being tracked starting in Zulip 8.0,
|
|
or because it was created via a data import tool
|
|
or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 292).
|
|
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
creator_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who created this user group.
|
|
|
|
A `null` value means the user group has no recorded creator, which is often
|
|
because the group predates the metadata being tracked starting in Zulip 8.0,
|
|
or because it was created via a data import tool
|
|
or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 292).
|
|
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
members:
|
|
type: array
|
|
description: |
|
|
The integer user IDs of the user group's members, which
|
|
are guaranteed to be non-deactivated users in the organization.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 303), this
|
|
list also included deactivated users who were members of
|
|
the user group before being deactivated.
|
|
items:
|
|
type: integer
|
|
direct_subgroup_ids:
|
|
type: array
|
|
description: |
|
|
The integer user group IDs of the direct subgroups.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Introduced in feature level 127 as `subgroups`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
items:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
description: |
|
|
User group name.
|
|
is_system_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is a system group which cannot be
|
|
modified by users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 93).
|
|
can_add_members_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to add members to this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 305). Previously, this
|
|
permission was controlled by the `can_manage_group` setting.
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_join_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to join this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 301).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_leave_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to leave this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 308).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_manage_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [manage this user group][manage-user-groups].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 283).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[manage-user-groups]: /help/manage-user-groups
|
|
can_mention_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [mention this user group][mentions].
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
|
|
always the integer form of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 8.0 (feature level 198), this setting was named
|
|
`can_mention_group_id`.
|
|
|
|
New in Zulip 8.0 (feature level 191). Previously, groups could be
|
|
mentioned only if they were not [system groups][system-groups].
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[mentions]: /help/mention-a-user-or-group
|
|
deactivated:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is deactivated. Deactivated groups
|
|
cannot be used as a subgroup of another group or used for
|
|
any other purpose.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 290).
|
|
description: |
|
|
A list of `user_group` objects.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_groups":
|
|
[
|
|
{
|
|
"description": "Owners of this organization",
|
|
"id": 1,
|
|
"creator_id": null,
|
|
"date_created": null,
|
|
"name": "role:owners",
|
|
"members": [1],
|
|
"direct_subgroup_ids": [],
|
|
"is_system_group": true,
|
|
"can_add_members_group": 16,
|
|
"can_join_group": 16,
|
|
"can_leave_group": 15,
|
|
"can_manage_group": 16,
|
|
"can_mention_group": 11,
|
|
},
|
|
{
|
|
"description": "Administrators of this organization, including owners",
|
|
"id": 2,
|
|
"creator_id": null,
|
|
"date_created": null,
|
|
"name": "role:administrators",
|
|
"members": [2],
|
|
"direct_subgroup_ids": [1],
|
|
"is_system_group": true,
|
|
"can_add_members_group": 17,
|
|
"can_join_group": 17,
|
|
"can_leave_group": 15,
|
|
"can_manage_group": 17,
|
|
"can_mention_group": 12,
|
|
},
|
|
{
|
|
"description": "Characters of Hamlet",
|
|
"id": 3,
|
|
"creator_id": null,
|
|
"date_created": 1717484476,
|
|
"name": "hamletcharacters",
|
|
"members": [3, 4],
|
|
"direct_subgroup_ids": [],
|
|
"is_system_group": false,
|
|
"can_add_members_group": 20,
|
|
"can_join_group": 20,
|
|
"can_leave_group": 15,
|
|
"can_manage_group": 20,
|
|
"can_mention_group": 13,
|
|
},
|
|
],
|
|
}
|
|
/user_groups/{user_group_id}/subgroups:
|
|
post:
|
|
operationId: update-user-group-subgroups
|
|
summary: Update subgroups of a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Update the subgroups of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- delete
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
delete:
|
|
description: |
|
|
The list of user group IDs to be removed from the user group.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [10]
|
|
add:
|
|
description: |
|
|
The list of user group IDs to be added to the user group.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [10]
|
|
encoding:
|
|
delete:
|
|
contentType: application/json
|
|
add:
|
|
contentType: application/json
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
get:
|
|
operationId: get-user-group-subgroups
|
|
summary: Get subgroups of a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Get the subgroups of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- name: direct_subgroup_only
|
|
in: query
|
|
description: |
|
|
Whether to consider only direct subgroups of the user group
|
|
or subgroups of subgroups also.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
required: false
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subgroups:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the IDs of subgroups of the user group.
|
|
example:
|
|
{"msg": "", "result": "success", "subgroups": [2, 3]}
|
|
/user_groups/{user_group_id}/members/{user_id}:
|
|
get:
|
|
operationId: get-is-user-group-member
|
|
summary: Get user group membership status
|
|
tags: ["users"]
|
|
description: |
|
|
Check whether a user is member of user group.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 303),
|
|
this would return true when passed a deactivated user
|
|
who was a member of the user group before being deactivated.
|
|
|
|
New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/DirectMemberOnly"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
is_user_group_member:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is member of user group.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"is_user_group_member": false,
|
|
}
|
|
/user_groups/{user_group_id}/deactivate:
|
|
post:
|
|
operationId: deactivate-user-group
|
|
summary: Deactivate a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Deactivate a user group. Deactivated user groups cannot be
|
|
used for mentions, permissions, or any other purpose, but can
|
|
be reactivated or renamed.
|
|
|
|
Deactivating user groups is preferable to deleting them from
|
|
the database, since the deactivation model allows audit logs
|
|
of changes to sensitive group-valued permissions to be
|
|
maintained.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 290).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user group",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response when the user group ID is invalid.
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "CANNOT_DEACTIVATE_GROUP_IN_USE",
|
|
"msg": "Cannot deactivate user group in use.",
|
|
"objections":
|
|
[
|
|
{
|
|
"type": "realm",
|
|
"settings":
|
|
["can_create_public_channel_group"],
|
|
},
|
|
],
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response when the user group being deactivated
|
|
is used for a setting or as a subgroup.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 298). Previously,
|
|
this error returned the `"BAD_REQUEST"` code.
|
|
/real-time:
|
|
# This entry is a hack; it exists to give us a place to put the text
|
|
# documenting the parameters for call_on_each_event and friends.
|
|
post:
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
(Ignored)
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
event_types:
|
|
$ref: "#/components/schemas/Event_types"
|
|
narrow:
|
|
$ref: "#/components/schemas/Narrow"
|
|
all_public_streams:
|
|
$ref: "#/components/schemas/AllPublicChannels"
|
|
encoding:
|
|
event_types:
|
|
contentType: application/json
|
|
narrow:
|
|
contentType: application/json
|
|
all_public_streams:
|
|
contentType: application/json
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
# Makeshift response for this hack entry.
|
|
"200":
|
|
description: Success
|
|
/rest-error-handling:
|
|
post:
|
|
operationId: rest-error-handling
|
|
summary: Error handling
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
Common error to many endpoints
|
|
responses:
|
|
"400":
|
|
description: |
|
|
Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InvalidApiKeyError"
|
|
- $ref: "#/components/schemas/MissingArgumentError"
|
|
- $ref: "#/components/schemas/IncompatibleParametersError"
|
|
- $ref: "#/components/schemas/UserNotAuthorizedError"
|
|
"401":
|
|
description: |
|
|
Unauthorized.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/UserDeactivatedError"
|
|
- $ref: "#/components/schemas/RealmDeactivatedError"
|
|
"429":
|
|
description: |
|
|
Rate limit exceeded.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RateLimitedError"
|
|
/zulip-outgoing-webhook:
|
|
post:
|
|
operationId: zulip-outgoing-webhooks
|
|
summary: Outgoing webhooks
|
|
tags: ["webhooks"]
|
|
description: |
|
|
Outgoing webhooks allow you to build or set up Zulip integrations which are
|
|
notified when certain types of messages are sent in Zulip.
|
|
responses:
|
|
"200":
|
|
description: |
|
|
Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
This is an example of the JSON payload that the Zulip server will `POST`
|
|
to your server:
|
|
properties:
|
|
bot_email:
|
|
type: string
|
|
description: |
|
|
Email of the bot user.
|
|
bot_full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the bot user.
|
|
data:
|
|
type: string
|
|
description: |
|
|
The message content, in raw Markdown format (not rendered to HTML).
|
|
trigger:
|
|
type: string
|
|
description: |
|
|
What aspect of the message triggered the outgoing webhook notification.
|
|
Possible values include `direct_message` and `mention`.
|
|
|
|
**Changes**: In Zulip 8.0 (feature level 201), renamed the trigger
|
|
`private_message` to `direct_message`.
|
|
token:
|
|
type: string
|
|
description: |
|
|
A string of alphanumeric characters that can be used to authenticate the
|
|
webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot
|
|
in the `zuliprc` file downloaded when creating the bot.
|
|
message:
|
|
description: |
|
|
A dictionary containing details on the message that triggered the
|
|
outgoing webhook, in the format used by [`GET /messages`](/api/get-messages).
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The content/body of the message rendered in HTML.
|
|
example:
|
|
{
|
|
"data": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
|
|
"trigger": "mention",
|
|
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
|
|
"message":
|
|
{
|
|
"subject": "Verona2",
|
|
"sender_email": "iago@zulip.com",
|
|
"timestamp": 1527876931,
|
|
"client": "website",
|
|
"submessages": [],
|
|
"recipient_id": 20,
|
|
"topic_links": [],
|
|
"sender_full_name": "Iago",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
|
|
"rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing webhook test</span> Zulip is the world\u2019s most productive group chat!</p>",
|
|
"sender_id": 5,
|
|
"stream_id": 5,
|
|
"content": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
|
|
"display_recipient": "Verona",
|
|
"type": "stream",
|
|
"id": 112,
|
|
"is_me_message": false,
|
|
"reactions": [],
|
|
"sender_realm_str": "zulip",
|
|
},
|
|
"bot_email": "outgoing-bot@localhost",
|
|
"bot_full_name": "Outgoing webhook test",
|
|
}
|
|
|
|
/calls/bigbluebutton/create:
|
|
get:
|
|
tags: ["channels"]
|
|
operationId: create-big-blue-button-video-call
|
|
summary: Create BigBlueButton video call
|
|
description: |
|
|
Create a video call URL for a BigBlueButton video call.
|
|
Requires [BigBlueButton](/integrations/doc/big-blue-button)
|
|
to be configured on the Zulip server.
|
|
parameters:
|
|
- in: query
|
|
name: meeting_name
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: |
|
|
Meeting name for the BigBlueButton video call.
|
|
example: "test_channel meeting"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
url:
|
|
description: |
|
|
The URL for the BigBlueButton video call.
|
|
type: string
|
|
example: "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22",
|
|
}
|
|
|
|
components:
|
|
#######################
|
|
# Security definitions
|
|
#######################
|
|
securitySchemes:
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
description: |
|
|
Basic authentication, with the user's email as the username, and the API
|
|
key as the password. The API key can be fetched using the
|
|
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
|
|
|
|
schemas:
|
|
IgnoredParametersUnsupported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
An array of any parameters sent in the request that are not
|
|
supported by the endpoint.
|
|
|
|
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
|
|
for details on this and its change history.
|
|
EventIdSchema:
|
|
type: integer
|
|
description: |
|
|
The ID of the event. Events appear in increasing order but may not be consecutive.
|
|
EventTypeSchema:
|
|
type: string
|
|
description: |
|
|
The event's type, relevant both for client-side dispatch and server-side
|
|
filtering by event type in [POST /register](/api/register-queue).
|
|
Anchor:
|
|
type: string
|
|
Attachments:
|
|
type: object
|
|
description: |
|
|
Dictionary containing details of a file uploaded by a user.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID for the attachment.
|
|
name:
|
|
type: string
|
|
description: |
|
|
Name of the uploaded file.
|
|
path_id:
|
|
type: string
|
|
description: |
|
|
A representation of the path of the file within the
|
|
repository of user-uploaded files. If the `path_id` of a
|
|
file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
|
|
`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
|
|
size:
|
|
type: integer
|
|
description: |
|
|
Size of the file in bytes.
|
|
create_time:
|
|
type: integer
|
|
description: |
|
|
Time when the attachment was uploaded as a UNIX timestamp
|
|
multiplied by 1000 (matching the format of getTime() in JavaScript).
|
|
|
|
**Changes**: Changed in Zulip 3.0 (feature level 22). This field was
|
|
previously a floating point number.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Contains basic details on any Zulip messages that have been
|
|
sent referencing this [uploaded file](/api/upload-file).
|
|
This includes messages sent by any user in the Zulip
|
|
organization who sent a message containing a link to the
|
|
uploaded file.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
date_sent:
|
|
type: integer
|
|
description: |
|
|
Time when the message was sent as a UNIX timestamp
|
|
multiplied by 1000 (matching the format of getTime() in JavaScript).
|
|
|
|
**Changes**: Changed in Zulip 3.0 (feature level 22). This
|
|
field was previously strangely called `name` and was a floating
|
|
point number.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique message ID. Messages should always be
|
|
displayed sorted by ID.
|
|
BasicChannel:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicChannelBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
is_archived: {}
|
|
description: {}
|
|
date_created: {}
|
|
creator_id:
|
|
nullable: true
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group: {}
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the channel per week, as
|
|
estimated based on recent weeks, rounded to the nearest integer.
|
|
|
|
If `null`, no information is provided on the average traffic.
|
|
This can be because the channel was recently created and there
|
|
is insufficient data to make an estimate, or because the server
|
|
wishes to omit this information for this client, this realm, or
|
|
this endpoint or type of event.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 199). Previously, this
|
|
statistic was available only in subscription objects.
|
|
required:
|
|
- stream_id
|
|
- name
|
|
- is_archived
|
|
- description
|
|
- date_created
|
|
- creator_id
|
|
- invite_only
|
|
- rendered_description
|
|
- is_web_public
|
|
- stream_post_policy
|
|
- message_retention_days
|
|
- history_public_to_subscribers
|
|
- first_message_id
|
|
- is_announcement_only
|
|
- can_remove_subscribers_group
|
|
- stream_weekly_traffic
|
|
DefaultChannel:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicChannelBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
is_archived: {}
|
|
description: {}
|
|
date_created: {}
|
|
creator_id:
|
|
nullable: true
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group: {}
|
|
required:
|
|
- stream_id
|
|
- name
|
|
- is_archived
|
|
- description
|
|
- date_created
|
|
- creator_id
|
|
- invite_only
|
|
- rendered_description
|
|
- is_web_public
|
|
- stream_post_policy
|
|
- message_retention_days
|
|
- history_public_to_subscribers
|
|
- first_message_id
|
|
- is_announcement_only
|
|
- can_remove_subscribers_group
|
|
BasicChannelBase:
|
|
type: object
|
|
description: |
|
|
Object containing basic details about the channel.
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the channel.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the channel.
|
|
is_archived:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating whether the channel is [archived](/help/archive-a-channel).
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 315).
|
|
Previously, this endpoint never returned archived channels.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The short description of the channel in text/markdown format,
|
|
intended to be used to prepopulate UI for editing a channel's
|
|
description.
|
|
date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the channel was created, in UTC seconds.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
creator_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who created this channel.
|
|
|
|
A `null` value means the channel has no recorded creator, which is often
|
|
because the channel is very old, or because it was created via a data
|
|
import tool or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 254).
|
|
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
invite_only:
|
|
type: boolean
|
|
description: |
|
|
Specifies whether the channel is private or not.
|
|
Only people who have been invited can access a private channel.
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
The short description of the channel rendered as HTML, intended to
|
|
be used when displaying the channel description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Whether the channel has been configured to allow unauthenticated
|
|
access to its message history from the web.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
stream_post_policy:
|
|
type: integer
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the channel.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
message_retention_days:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Number of days that messages sent to this channel will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). There are two special values:
|
|
|
|
- `null`, the default, means the channel will inherit the organization
|
|
level setting.
|
|
- `-1` encodes retaining messages in this channel forever.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 17).
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Whether the history of the channel is public to its subscribers.
|
|
|
|
Currently always true for public channels (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
first_message_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the first message in the channel.
|
|
|
|
Intended to help clients determine whether they need to display
|
|
UI like the "show all topics" widget that would suggest the channel
|
|
has older history that can be accessed.
|
|
|
|
Is `null` for channels with no message history.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
is_announcement_only:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether the given channel is announcement only or not.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
can_remove_subscribers_group:
|
|
$ref: "#/components/schemas/CanRemoveSubscribersGroup"
|
|
BasicBot:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicBotBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
full_name: {}
|
|
api_key: {}
|
|
default_sending_stream:
|
|
nullable: true
|
|
default_events_register_stream:
|
|
nullable: true
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id:
|
|
nullable: true
|
|
services: {}
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean describing whether the user account has been deactivated.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 222). Previously
|
|
we sent `realm_user` event with `op` field set to `remove`
|
|
when deactivating a bot and `realm_user` event with `op`
|
|
field set to `add` when reactivating a bot.
|
|
BasicBotBase:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the bot.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the bot.
|
|
api_key:
|
|
type: string
|
|
description: |
|
|
The API key of the bot which it uses to make API requests.
|
|
default_sending_stream:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The default sending channel of the bot. If `null`, the bot doesn't
|
|
have a default sending channel.
|
|
default_events_register_stream:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The default channel for which the bot receives events/register data.
|
|
If `null`, the bot doesn't have such a default channel.
|
|
default_all_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Whether the bot can send messages to all channels by default.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
The URL of the bot's avatar.
|
|
owner_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The user ID of the bot's owner.
|
|
|
|
If `null`, the bot has no owner.
|
|
services:
|
|
type: array
|
|
description: |
|
|
An array containing extra configuration fields only relevant for
|
|
outgoing webhook bots and embedded bots. This is always a single-element
|
|
array.
|
|
|
|
We consider this part of the Zulip API to be unstable; it is used only
|
|
for UI elements for administering bots and is likely to change.
|
|
items:
|
|
description: |
|
|
Object with extra configuration details for the bot. The fields in the
|
|
object depend on the type of bot.
|
|
oneOf:
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the bot is an outgoing webhook.
|
|
properties:
|
|
base_url:
|
|
type: string
|
|
description: |
|
|
The URL the outgoing webhook is configured to post to.
|
|
token:
|
|
type: string
|
|
description: |
|
|
A unique token that the third-party service can use to confirm
|
|
that the request is indeed coming from Zulip.
|
|
interface:
|
|
type: integer
|
|
description: |
|
|
An integer indicating what format requests are posted in:
|
|
|
|
- 1 = Zulip's native outgoing webhook format.
|
|
- 2 = Emulate the Slack outgoing webhook format.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the bot is an embedded bot.
|
|
properties:
|
|
service_name:
|
|
type: string
|
|
description: |
|
|
The name of the bot.
|
|
config_data:
|
|
$ref: "#/components/schemas/BotConfiguration"
|
|
Bot:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicBotBase"
|
|
- description: |
|
|
Object containing details of a bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
full_name: {}
|
|
api_key: {}
|
|
default_sending_stream:
|
|
nullable: true
|
|
default_events_register_stream:
|
|
nullable: true
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id:
|
|
nullable: true
|
|
services: {}
|
|
email:
|
|
type: string
|
|
description: |
|
|
The email of the bot.
|
|
bot_type:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
An integer describing the type of bot:
|
|
|
|
- `1` for a `Generic` bot.
|
|
- `2` for an `Incoming webhook` bot.
|
|
- `3` for an `Outgoing webhook` bot.
|
|
- `4` for an `Embedded` bot.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean describing whether the user account has been deactivated.
|
|
BotConfiguration:
|
|
type: object
|
|
description: |
|
|
A dictionary of string key/value pairs, which describe the configuration
|
|
for the bot. These are usually details like API keys, and are unique to
|
|
the integration/bot. Can be an empty dictionary.
|
|
additionalProperties:
|
|
description: |
|
|
`{config_key}`: Description/value of the configuration data key.
|
|
type: string
|
|
WebhookConfigOption:
|
|
type: array
|
|
description: |
|
|
An array of configuration options where each option is an
|
|
object containing a unique identifier, a human-readable name,
|
|
and a validation function name hinting how to verify the
|
|
correct input format.
|
|
|
|
This is an unstable API expected to be used only by the Zulip web
|
|
apps. Please discuss in chat.zulip.org before using it.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 318).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
A key for the configuration option to use in generated URLs.
|
|
label:
|
|
type: string
|
|
description: |
|
|
A human-readable label of the configuration option.
|
|
validator:
|
|
type: string
|
|
description: |
|
|
The name of the validator function for the configuration
|
|
option. Currently generated values are `check_bool` and
|
|
`check_str`.
|
|
CustomProfileField:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing the details of a custom profile field configured
|
|
for this organization.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field. This will be referenced in the custom
|
|
profile fields section of user objects.
|
|
type:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the type of the custom profile field, which determines
|
|
how it is configured and displayed to users.
|
|
|
|
See the [Custom profile fields](/help/custom-profile-fields#profile-field-types)
|
|
article for details on what each type means.
|
|
|
|
- **1**: Short text
|
|
- **2**: Long text
|
|
- **3**: List of options
|
|
- **4**: Date picker
|
|
- **5**: Link
|
|
- **6**: Person picker
|
|
- **7**: External account
|
|
- **8**: Pronouns
|
|
|
|
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
|
|
order:
|
|
type: integer
|
|
description: |
|
|
Custom profile fields are displayed in both settings UI and
|
|
UI showing users' profiles in increasing `order`.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the custom profile field.
|
|
hint:
|
|
type: string
|
|
description: |
|
|
The help text to be displayed for the custom profile field in user-facing
|
|
settings UI for configuring custom profile fields.
|
|
field_data:
|
|
type: string
|
|
description: |
|
|
Field types 3 (List of options) and 7 (External account) support storing
|
|
additional configuration for the field type in the `field_data` attribute.
|
|
|
|
For field type 3 (List of options), this attribute is a JSON dictionary
|
|
defining the choices and the order they will be displayed in the
|
|
dropdown UI for individual users to select an option.
|
|
|
|
The interface for field type 7 is not yet stabilized.
|
|
display_in_profile_summary:
|
|
type: boolean
|
|
description: |
|
|
Whether the custom profile field, display or not on the user card.
|
|
|
|
Currently it's value not allowed to be `true` of `Long text` and `Person picker`
|
|
[profile field types](/help/custom-profile-fields#profile-field-types).
|
|
|
|
This field is only included when its value is `true`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 146).
|
|
default: false
|
|
required:
|
|
type: boolean
|
|
description: |
|
|
Whether an organization administrator has configured this profile field as
|
|
required.
|
|
|
|
Because the required property is mutable, clients cannot assume that a required
|
|
custom profile field has a value. The Zulip web application displays a prominent
|
|
banner to any user who has not set a value for a required field.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 244).
|
|
editable_by_user:
|
|
type: boolean
|
|
description: |
|
|
Whether regular users can edit this profile field on their own account.
|
|
|
|
Note that organization administrators can edit custom profile fields for any user
|
|
regardless of this setting.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 296).
|
|
default: true
|
|
required:
|
|
- id
|
|
- type
|
|
- order
|
|
- name
|
|
- hint
|
|
- required
|
|
- editable_by_user
|
|
OnboardingStep:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing details of a single onboarding step.
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the onboarding step. Valid value is `"one_time_notice"`.
|
|
|
|
**Changes**: Removed type `"hotspot"` in Zulip 9.0 (feature level 259).
|
|
|
|
New in Zulip 8.0 (feature level 233).
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the onboarding step.
|
|
RealmAuthenticationMethod:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: |
|
|
Boolean describing whether the authentication method (i.e. its key)
|
|
is enabled in this organization.
|
|
available:
|
|
type: boolean
|
|
description: |
|
|
Boolean describing whether the authentication method is available for use.
|
|
If false, the organization is not eligible to enable the authentication
|
|
method.
|
|
unavailable_reason:
|
|
type: string
|
|
description: |
|
|
Reason why the authentication method is unavailable. This field is optional
|
|
and is only present when 'available' is false.
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary describing the properties of an authentication method for the
|
|
organization - its enabled status and availability for use by the
|
|
organization.
|
|
RealmEmoji:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
`{emoji_id}`: Object containing details about the emoji with
|
|
the specified ID. It has the following properties:
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: |
|
|
The ID for this emoji, same as the object's key.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The user-friendly name for this emoji. Users in the organization
|
|
can use this emoji by writing this name between colons (`:name :`).
|
|
source_url:
|
|
type: string
|
|
description: |
|
|
The path relative to the organization's URL where the
|
|
emoji's image can be found.
|
|
still_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
Only non-null when the emoji's image is animated.
|
|
|
|
The path relative to the organization's URL where a still
|
|
(not animated) version of the emoji can be found. (This is
|
|
currently always the first frame of the animation).
|
|
|
|
This is useful for clients to display the emoji in contexts
|
|
where continuously animating it would be a bad user experience
|
|
(E.g. because it would be distracting).
|
|
|
|
**Changes**: New in Zulip 5.0 (added as optional field in
|
|
feature level 97 and then made mandatory, but nullable, in
|
|
feature level 113).
|
|
deactivated:
|
|
type: boolean
|
|
description: |
|
|
Whether the emoji has been deactivated or not.
|
|
author_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The user ID of the user who uploaded the custom emoji.
|
|
Will be `null` if the uploader is unknown.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 7). Previously
|
|
was accessible via an `author` object with an `id` field.
|
|
RealmDomain:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the newly added domain.
|
|
properties:
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The new allowed domain.
|
|
allow_subdomains:
|
|
type: boolean
|
|
description: |
|
|
Whether subdomains are allowed for this domain.
|
|
RealmPlayground:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about a realm playground.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID for the realm playground.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The user-visible display name of the playground. Clients
|
|
should display this in UI for picking which playground to
|
|
open a code block in, to differentiate between multiple
|
|
configured playground options for a given pygments
|
|
language.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
pygments_language:
|
|
type: string
|
|
description: |
|
|
The name of the Pygments language lexer for that
|
|
programming language.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
|
|
compliant URL template for the playground. The template contains
|
|
exactly one variable named `code`, which determines how the
|
|
extracted code should be substituted in the playground URL.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 196). This replaced the
|
|
`url_prefix` parameter, which was used to construct URLs by just
|
|
concatenating url_prefix and code.
|
|
RealmExport:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about a
|
|
[data export](/help/export-your-organization).
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the data export.
|
|
acting_user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who created the data export.
|
|
export_time:
|
|
type: number
|
|
description: |
|
|
The UNIX timestamp of when the data export was started.
|
|
deleted_timestamp:
|
|
type: number
|
|
nullable: true
|
|
description: |
|
|
The UNIX timestamp of when the data export was deleted.
|
|
|
|
Will be `null` if the data export has not been deleted.
|
|
failed_timestamp:
|
|
type: number
|
|
nullable: true
|
|
description: |
|
|
The UNIX timestamp of when the data export failed.
|
|
|
|
Will be `null` if the data export succeeded, or if it's
|
|
still being generated.
|
|
export_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL to download the generated data export.
|
|
|
|
Will be `null` if the data export failed, or if it's
|
|
still being generated.
|
|
pending:
|
|
type: boolean
|
|
description: |
|
|
Whether the data export is pending, which indicates it
|
|
is still being generated, or if it succeeded, failed or
|
|
was deleted before being generated.
|
|
|
|
Depending on the size of the organization, it can take
|
|
anywhere from seconds to an hour to generate the data
|
|
export.
|
|
export_type:
|
|
type: integer
|
|
description: |
|
|
Whether the data export is a public or a standard data export.
|
|
|
|
- 1 = Public data export.
|
|
- 2 = Standard data export.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 304). Previously,
|
|
the export type was not included in these objects because only
|
|
public data exports could be created or listed via the API or UI.
|
|
UserGroup:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user group's attributes.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the user group.
|
|
date_created:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The UNIX timestamp for when the user group was created, in UTC seconds.
|
|
|
|
A `null` value means the user group has no recorded date, which is often
|
|
because the user group is very old, or because it was created via a data
|
|
import tool or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 292).
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
creator_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who created this user group.
|
|
|
|
A `null` value means the user group has no recorded creator, which is often
|
|
because the user group is very old, or because it was created via a data
|
|
import tool or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 292).
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
description:
|
|
type: string
|
|
description: |
|
|
The description of the user group.
|
|
members:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the ID of the users who are
|
|
members of this user group.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 303), this
|
|
list also included deactivated users who were members of
|
|
the user group before being deactivated.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the ID of the direct_subgroups of
|
|
this user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Introduced in feature level 127 as `subgroups`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group.
|
|
is_system_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is a system group which cannot be
|
|
directly modified by users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 93).
|
|
can_add_members_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to add members to this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 305). Previously, this
|
|
permission was controlled by the `can_manage_group` setting.
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_join_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to join this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 301).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_leave_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to leave this user group.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 308).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
can_manage_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [manage this user group][manage-user-groups].
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 283).
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[manage-user-groups]: /help/manage-user-groups
|
|
can_mention_group:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users who
|
|
have permission to [mention this user group][mentions].
|
|
|
|
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
|
|
always the integer form of a [group-setting value][setting-values].
|
|
|
|
Before Zulip 8.0 (feature level 198), this setting was named
|
|
`can_mention_group_id`.
|
|
|
|
New in Zulip 8.0 (feature level 191). Previously, groups could be
|
|
mentioned only if they were not [system groups][system-groups].
|
|
|
|
Will be one of the following:
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
[system-groups]: /api/group-setting-values#system-groups
|
|
[mentions]: /help/mention-a-user-or-group
|
|
deactivated:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is deactivated. Deactivated groups
|
|
cannot be used as a subgroup of another group or used for
|
|
any other purpose.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 290).
|
|
GroupSettingValue:
|
|
oneOf:
|
|
- type: integer
|
|
description: |
|
|
The ID of the [user group](/help/user-groups) with this permission.
|
|
- type: object
|
|
additionalProperties: false
|
|
properties:
|
|
direct_members:
|
|
description: |
|
|
The list of IDs of individual users in the collection of users with this permission.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 303), this list would include
|
|
deactivated users who had the permission before being deactivated.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
direct_subgroups:
|
|
description: |
|
|
The list of IDs of the groups in the collection of users with this permission.
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
An object with these fields:
|
|
Invite:
|
|
type: object
|
|
description: |
|
|
A dictionary containing details about an [invitation](/help/invite-new-users).
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the invitation.
|
|
|
|
Note that email invitations and reusable invitation links are stored
|
|
in different database tables on the server, so each ID is guaranteed
|
|
to be unique in combination with the boolean value of `is_multiuse`,
|
|
e.g. there can only be one invitation with `id: 1` and `is_multiuse:
|
|
true`.
|
|
invited_by_user_id:
|
|
type: integer
|
|
description: |
|
|
The [user ID](/api/get-user) of the user who created the invitation.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 22), replacing the `ref`
|
|
field which contained the Zulip display email address of the user who
|
|
created the invitation.
|
|
invited:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the invitation was created, in UTC seconds.
|
|
expiry_date:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The UNIX timestamp for when the invitation will expire, in UTC seconds.
|
|
If `null`, the invitation never expires.
|
|
invited_as:
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
description: |
|
|
The [organization-level role](/api/roles-and-permissions) of the user that
|
|
is created when the invitation is accepted.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
email:
|
|
type: string
|
|
description: |
|
|
The email address the invitation was sent to. This will not be present when
|
|
`is_multiuse` is `true` (i.e. the invitation is a reusable invitation link).
|
|
notify_referrer_on_join:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating whether the referrer has opted to receive a direct
|
|
message from [notification bot](/help/configure-automated-notices) when a user
|
|
account is created using this invitation.
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 267). Previously,
|
|
referrers always received such direct messages.
|
|
link_url:
|
|
type: string
|
|
description: |
|
|
The URL of the reusable invitation link. This will not be present when
|
|
`is_multiuse` is `false` (i.e. the invitation is an email invitation).
|
|
is_multiuse:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the [invitation](/help/invite-new-users) is a
|
|
reusable invitation link or an email invitation.
|
|
InviteExpirationParameter:
|
|
description: |
|
|
The number of minutes before the invitation will expire. If `null`, the
|
|
invitation will never expire. If unspecified, the server will use a default
|
|
value (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which
|
|
defaults to 14400, i.e. 10 days) for when the invitation will expire.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an
|
|
`invite_expires_in_days` parameter, which specified the duration in days instead
|
|
of minutes.
|
|
type: integer
|
|
nullable: true
|
|
example: 14400
|
|
InviteRoleParameter:
|
|
description: |
|
|
The [organization-level role](/api/roles-and-permissions) of the user that is
|
|
created when the invitation is accepted.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
|
|
Users can only create invitation links for
|
|
[roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels)
|
|
as their own. For example, a moderator cannot invite someone to be an owner
|
|
or administrator, but they can invite them to be a moderator or member.
|
|
|
|
**Changes**: In Zulip 4.0 (feature level 61), added support for inviting
|
|
users as moderators.
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
default: 400
|
|
example: 600
|
|
Subscriptions:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of a channel.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of a channel.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-channel-description) of the channel in text/markdown format,
|
|
intended to be used to prepopulate UI for editing a channel's
|
|
description.
|
|
|
|
See also `rendered_description`.
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-channel-description) of the channel rendered as HTML, intended to
|
|
be used when displaying the channel description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
|
|
See also `description`.
|
|
date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the channel was created, in UTC seconds.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
creator_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who created this channel.
|
|
|
|
A `null` value means the channel has no recorded creator, which is often
|
|
because the channel is very old, or because it was created via a data
|
|
import tool or [management command][management-commands].
|
|
|
|
**Changes**: New in Zulip 9.0 (feature level 254).
|
|
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
invite_only:
|
|
type: boolean
|
|
description: |
|
|
Specifies whether the channel is private or not.
|
|
Only people who have been invited can access a private channel.
|
|
# TODO: This subscribers item should probably be declared optional more
|
|
# explicitly in the OpenAPI format?
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list of user IDs of users who are also subscribed
|
|
to a given channel. Included only if `include_subscribers` is `true`.
|
|
desktop_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether desktop notifications
|
|
are enabled for the given channel.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, `enable_stream_desktop_notifications`, for
|
|
this channel.
|
|
email_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether email notifications
|
|
are enabled for the given channel.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, `enable_stream_email_notifications`, for
|
|
this channel.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether wildcard mentions
|
|
trigger notifications as though they were personal
|
|
mentions in this channel.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, wildcard_mentions_notify, for
|
|
this channel.
|
|
push_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether push notifications
|
|
are enabled for the given channel.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, `enable_stream_push_notifications`, for
|
|
this channel.
|
|
audible_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether audible notifications
|
|
are enabled for the given channel.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, `enable_stream_audible_notifications`, for
|
|
this channel.
|
|
pin_to_top:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the given channel has been pinned
|
|
to the top.
|
|
is_muted:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has muted the channel. Muted channels do
|
|
not count towards your total unread count and do not show
|
|
up in the `Combined feed` view (previously known as `All messages`).
|
|
|
|
**Changes**: Prior to Zulip 2.1.0, this feature was
|
|
represented by the more confusingly named `in_home_view` (with the
|
|
opposite value, `in_home_view=!is_muted`).
|
|
in_home_view:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Legacy property for if the given channel is muted, with inverted meaning.
|
|
|
|
**Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted`
|
|
where available.
|
|
is_announcement_only:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether only organization administrators can post to the channel.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Whether the channel has been configured to allow unauthenticated
|
|
access to its message history from the web.
|
|
color:
|
|
type: string
|
|
description: |
|
|
The user's personal color for the channel.
|
|
stream_post_policy:
|
|
type: integer
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the channel.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
message_retention_days:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Number of days that messages sent to this channel will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). There are two special values:
|
|
|
|
- `null`, the default, means the channel will inherit the organization
|
|
level setting.
|
|
- `-1` encodes retaining messages in this channel forever.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 17).
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Whether the history of the channel is public to its subscribers.
|
|
|
|
Currently always true for public channels (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
first_message_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the first message in the channel.
|
|
|
|
Intended to help clients determine whether they need to display
|
|
UI like the "show all topics" widget that would suggest the channel
|
|
has older history that can be accessed.
|
|
|
|
Is `null` for channels with no message history.
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the channel per week, as
|
|
estimated based on recent weeks, rounded to the nearest integer.
|
|
|
|
If `null`, the channel was recently created and there is
|
|
insufficient data to estimate the average traffic.
|
|
can_remove_subscribers_group:
|
|
$ref: "#/components/schemas/CanRemoveSubscribersGroup"
|
|
is_archived:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating whether the channel is [archived](/help/archive-a-channel).
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 315).
|
|
Previously, subscriptions only included active
|
|
channels. Note that some endpoints will never return archived
|
|
channels unless the client declares explicit support for
|
|
them via the `archived_channels` client capability.
|
|
DefaultChannelGroup:
|
|
type: object
|
|
description: |
|
|
Dictionary containing details of a default channel
|
|
group.
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
Name of the default channel group.
|
|
description:
|
|
type: string
|
|
description: |
|
|
Description of the default channel group.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the default channel group.
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array containing details about the channels
|
|
in the default channel group.
|
|
items:
|
|
$ref: "#/components/schemas/DefaultChannel"
|
|
EmailAddressVisibility:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for [which other users][help-email-visibility]
|
|
in this organization can see the user's real email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
EmojiReaction:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who added the reaction.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
|
|
object is deprecated and will be removed in the future.
|
|
user:
|
|
type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Dictionary with data on the user who added the
|
|
reaction, including the user ID as the `id`
|
|
field. Note that reactions data received from the
|
|
[events API](/api/get-events) has a slightly different
|
|
`user` dictionary format, with the user ID field
|
|
called `user_id` instead.
|
|
|
|
**Changes**: Deprecated and to be removed in a future release
|
|
once core clients have migrated to use the adjacent `user_id`
|
|
field, which was introduced in Zulip 3.0 (feature level 2).
|
|
Clients supporting older Zulip server versions should use
|
|
the user ID mentioned in the description above as they would
|
|
the `user_id` field.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user.
|
|
is_mirror_dummy:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a mirror dummy.
|
|
EmojiBase:
|
|
type: object
|
|
properties:
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
Name of the emoji.
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
reaction_type:
|
|
type: string
|
|
enum:
|
|
- unicode_emoji
|
|
- realm_emoji
|
|
- zulip_extra_emoji
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
EmojiReactionEvent:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiBase"
|
|
- properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who added the reaction.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
|
|
object is deprecated and will be removed in the future.
|
|
user:
|
|
type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Dictionary with data on the user who added the
|
|
reaction, including the user ID as the `user_id`
|
|
field.
|
|
|
|
**Changes**: Deprecated and to be removed in a future release
|
|
once core clients have migrated to use the adjacent `user_id`
|
|
field, which was introduced in Zulip 3.0 (feature level 2).
|
|
Clients supporting older Zulip server versions should use
|
|
the user ID mentioned in the description above as they would
|
|
the `user_id` field.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user.
|
|
is_mirror_dummy:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a mirror dummy.
|
|
MessagesEvent:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
MessagesBase:
|
|
type: object
|
|
description: |
|
|
Object containing details of the message.
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the message sender's avatar. Can be `null` only if
|
|
the current user has access to the sender's real email address
|
|
and `client_gravatar` was `true`.
|
|
|
|
If `null`, then the sender has not uploaded an avatar in Zulip,
|
|
and the client can compute the gravatar URL by hashing the
|
|
sender's email address, which corresponds in this case to their
|
|
real email address.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163), access to a
|
|
user's real email address was a realm-level setting. As of this
|
|
feature level, `email_address_visibility` is a user setting.
|
|
client:
|
|
type: string
|
|
description: |
|
|
A Zulip "client" string, describing what Zulip client
|
|
sent the message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content/body of the message.
|
|
content_type:
|
|
type: string
|
|
description: |
|
|
The HTTP `content_type` for the message content. This
|
|
will be `text/html` or `text/x-markdown`, depending on
|
|
whether `apply_markdown` was set.
|
|
display_recipient:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user.
|
|
is_mirror_dummy:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a mirror dummy.
|
|
description: |
|
|
Data on the recipient of the message;
|
|
either the name of a channel or a dictionary containing basic data on
|
|
the users who received the message.
|
|
edit_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
prev_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The content of the message immediately prior to this
|
|
edit event.
|
|
prev_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The rendered HTML representation of `prev_content`.
|
|
prev_stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's channel was edited.
|
|
|
|
The channel ID of the message immediately prior to this
|
|
edit event.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
prev_topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately prior to this
|
|
edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
Previously, this field was called `prev_subject`;
|
|
clients are recommended to rename `prev_subject` to
|
|
`prev_topic` if present for compatibility with
|
|
older Zulip servers.
|
|
stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's channel was edited.
|
|
|
|
The ID of the channel containing the message
|
|
immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for the edit.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user that made the edit.
|
|
|
|
Will be `null` only for edit history
|
|
events predating March 2017.
|
|
|
|
Clients can display edit history events where this
|
|
is `null` as modified by either the sender (for content
|
|
edits) or an unknown user (for topic edits).
|
|
required:
|
|
- user_id
|
|
- timestamp
|
|
description: |
|
|
An array of objects, with each object documenting the
|
|
changes in a previous edit made to the message,
|
|
ordered chronologically from most recent to least recent
|
|
edit.
|
|
|
|
Not present if the message has never been edited or if the realm has
|
|
[disabled viewing of message edit history][disable-edit-history].
|
|
|
|
Every object will contain `user_id` and `timestamp`.
|
|
|
|
The other fields are optional, and will be present or not
|
|
depending on whether the channel, topic, and/or message
|
|
content were modified in the edit event. For example, if
|
|
only the topic was edited, only `prev_topic` and `topic`
|
|
will be present in addition to `user_id` and `timestamp`.
|
|
|
|
[disable-edit-history]: /help/disable-message-edit-history
|
|
|
|
**Changes**: In Zulip 10.0 (feature level 284), removed the
|
|
`prev_rendered_content_version` field as it is an internal
|
|
server implementation detail not used by any client.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique message ID. Messages should always be
|
|
displayed sorted by ID.
|
|
is_me_message:
|
|
type: boolean
|
|
description: |
|
|
Whether the message is a [/me status message][status-messages]
|
|
|
|
[status-messages]: /help/format-your-message-using-markdown#status-messages
|
|
last_edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message was last edited,
|
|
in UTC seconds.
|
|
|
|
Not present if the message has never been edited.
|
|
reactions:
|
|
type: array
|
|
description: |
|
|
Data on any reactions to the message.
|
|
items:
|
|
$ref: "#/components/schemas/EmojiReaction"
|
|
recipient_id:
|
|
type: integer
|
|
description: |
|
|
A unique ID for the set of users receiving the
|
|
message (either a channel or group of users). Useful primarily
|
|
for hashing.
|
|
sender_email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address of the message's sender.
|
|
sender_full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the message's sender.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the message's sender.
|
|
sender_realm_str:
|
|
type: string
|
|
description: |
|
|
A string identifier for the realm the sender is in. Unique only within
|
|
the context of a given Zulip server.
|
|
|
|
E.g. on `example.zulip.com`, this will be `example`.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present for channel messages; the ID of the channel.
|
|
subject:
|
|
type: string
|
|
description: |
|
|
The `topic` of the message. Currently always `""` for direct messages,
|
|
though this could change if Zulip adds support for topics in direct
|
|
message conversations.
|
|
|
|
The field name is a legacy holdover from when topics were
|
|
called "subjects" and will eventually change.
|
|
submessages:
|
|
type: array
|
|
description: |
|
|
Data used for certain experimental Zulip integrations.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
msg_type:
|
|
type: string
|
|
description: |
|
|
The type of the message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The new content of the submessage.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message to which the submessage has been added.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the submessage.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message was sent,
|
|
in UTC seconds.
|
|
topic_links:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: |
|
|
The original link text present in the topic.
|
|
url:
|
|
type: string
|
|
description: |
|
|
The expanded target url which the link points to.
|
|
description: |
|
|
Data on any links to be included in the `topic`
|
|
line (these are generated by [custom linkification
|
|
filters](/help/add-a-custom-linkifier) that match content in the
|
|
message's topic.)
|
|
|
|
**Changes**: This field contained a list of urls before
|
|
Zulip 4.0 (feature level 46).
|
|
|
|
New in Zulip 3.0 (feature level 1). Previously, this field was called
|
|
`subject_links`; clients are recommended to rename `subject_links` to `topic_links`
|
|
if present for compatibility with older Zulip servers.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the message: `"stream"` or `"private"`.
|
|
ModernPresenceFormat:
|
|
type: object
|
|
description: |
|
|
`{user_id}`: Presence data (modern format) for the user with
|
|
the specified ID.
|
|
additionalProperties: false
|
|
properties:
|
|
active_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of the last time a client connected
|
|
to Zulip reported that the user was actually present
|
|
(e.g. via focusing a browser window or interacting
|
|
with a computer running the desktop app).
|
|
|
|
Clients should display users with a current
|
|
`active_timestamp` as fully present.
|
|
idle_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of the last time the user had a
|
|
client connected to Zulip, including idle clients
|
|
where the user hasn't interacted with the system
|
|
recently.
|
|
|
|
The Zulip server has no way of distinguishing whether
|
|
an idle web app user is at their computer, but hasn't
|
|
interacted with the Zulip tab recently, or simply left
|
|
their desktop computer on when they left.
|
|
|
|
Thus, clients should display users with a current
|
|
`idle_timestamp` but no current `active_timestamp` as
|
|
potentially present.
|
|
LegacyPresenceFormat:
|
|
type: object
|
|
description: |
|
|
`{client_name}` or `"aggregated"`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
|
|
contain two keys, `"website"` and `"aggregated"`, with identical data. The
|
|
server no longer stores which client submitted presence updates.
|
|
|
|
Previously, the `{client_name}` keys for these objects were the names of the
|
|
different clients where the user was logged in, for example `website` or
|
|
`ZulipDesktop`.
|
|
additionalProperties: false
|
|
properties:
|
|
client:
|
|
type: string
|
|
description: |
|
|
The client's platform name.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will
|
|
always be `"website"` as the server no longer stores which client
|
|
submitted presence data.
|
|
status:
|
|
type: string
|
|
enum:
|
|
- idle
|
|
- active
|
|
description: |
|
|
The status of the user on this client. Will be either `"idle"`
|
|
or `"active"`.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of when this client sent the user's presence
|
|
to the server with the precision of a second.
|
|
pushable:
|
|
type: boolean
|
|
description: |
|
|
Whether the client is capable of showing mobile/push notifications
|
|
to the user.
|
|
|
|
Not present in objects with the `"aggregated"` key.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), always
|
|
`false` when present as the server no longer stores which client
|
|
submitted presence data.
|
|
UserStatus:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
away:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
If present, the user has marked themself "away".
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
If present, the text content of the user's status message.
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
If present, the name for the emoji to associate with the user's status.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
If present, a unique identifier, defining the specific emoji codepoint
|
|
requested, within the namespace of the `reaction_type`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
reaction_type:
|
|
type: string
|
|
enum:
|
|
- unicode_emoji
|
|
- realm_emoji
|
|
- zulip_extra_emoji
|
|
description: |
|
|
If present, a string indicating the type of emoji. Each emoji
|
|
`reaction_type` has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
Draft:
|
|
type: object
|
|
description: |
|
|
A dictionary for representing a message draft.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the draft. It will only used whenever the drafts are
|
|
fetched. This field should not be specified when the draft is being
|
|
created or edited.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the draft. Either unaddressed (empty string), `"stream"`,
|
|
or `"private"` (for one-on-one and group direct messages).
|
|
enum:
|
|
- ""
|
|
- stream
|
|
- private
|
|
to:
|
|
type: array
|
|
description: |
|
|
An array of the tentative target audience IDs. For channel
|
|
messages, this should contain exactly 1 ID, the ID of the
|
|
target channel. For direct messages, this should be an array
|
|
of target user IDs. For unaddressed drafts, this is ignored,
|
|
and clients should send an empty array.
|
|
items:
|
|
type: integer
|
|
topic:
|
|
type: string
|
|
description: |
|
|
For channel message drafts, the tentative topic name. For direct
|
|
or unaddressed messages, this will be ignored and should ideally
|
|
be the empty string. Should not contain null bytes.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The body of the draft. Should not contain null bytes.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
A Unix timestamp (seconds only) representing when the draft was
|
|
last edited. When creating a draft, this key need not be present
|
|
and it will be filled in automatically by the server.
|
|
example: 1595479019
|
|
additionalProperties: false
|
|
required:
|
|
- type
|
|
- to
|
|
- topic
|
|
- content
|
|
SavedSnippet:
|
|
type: object
|
|
description: |
|
|
Object containing the details of the saved snippet.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the saved snippet.
|
|
title:
|
|
type: string
|
|
description: |
|
|
The title of the saved snippet.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content of the saved snippet in text/markdown format.
|
|
|
|
Clients should insert this content into a message when using
|
|
a saved snippet.
|
|
date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the saved snippet was created, in
|
|
UTC seconds.
|
|
ScheduledMessage:
|
|
type: object
|
|
description: |
|
|
Object containing details of the scheduled message.
|
|
properties:
|
|
scheduled_message_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the scheduled message, which can be used to
|
|
modify or delete the scheduled message.
|
|
|
|
This is different from the unique ID that the message will have
|
|
after it is sent.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the scheduled message. Either `"stream"` or `"private"`.
|
|
enum:
|
|
- stream
|
|
- private
|
|
to:
|
|
oneOf:
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
The scheduled message's tentative target audience.
|
|
|
|
For channel messages, it will be the unique ID of the target
|
|
channel. For direct messages, it will be an array with the
|
|
target users' IDs.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `type` is `"stream"`.
|
|
|
|
The topic for the channel message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content/body of the scheduled message, in text/markdown format.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The content/body of the scheduled message rendered in HTML.
|
|
scheduled_delivery_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message will be sent
|
|
by the server, in UTC seconds.
|
|
example: 1595479019
|
|
failed:
|
|
type: boolean
|
|
description: |
|
|
Whether the server has tried to send the scheduled message
|
|
and it failed to successfully send.
|
|
|
|
Clients that support unscheduling and editing scheduled messages
|
|
should display scheduled messages with `"failed": true` with an
|
|
indicator that the server failed to send the message at the
|
|
scheduled time, so that the user is aware of the failure and can
|
|
get the content of the scheduled message.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 181).
|
|
additionalProperties: false
|
|
required:
|
|
- scheduled_message_id
|
|
- type
|
|
- to
|
|
- content
|
|
- rendered_content
|
|
- scheduled_delivery_timestamp
|
|
- failed
|
|
GroupPermissionSetting:
|
|
description: |
|
|
Configuration for a group permission setting specifying the groups
|
|
to which the setting can be set to and the default values for the
|
|
setting.
|
|
additionalProperties: false
|
|
type: object
|
|
properties:
|
|
require_system_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the setting can only be set to a system user group.
|
|
allow_internet_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the setting can be set to `role:internet` system group.
|
|
allow_owners_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the setting can be set to `role:owners` system group.
|
|
allow_nobody_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the setting can be set to `role:nobody` system group.
|
|
allow_everyone_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the setting can be set to `role:everyone` system group.
|
|
|
|
If false, guest users cannot exercise this permission even if they are part of
|
|
the [group-setting value](/api/group-setting-values) for this setting.
|
|
default_group_name:
|
|
type: string
|
|
description: |
|
|
Name of the default group for the setting.
|
|
id_field_name:
|
|
type: string
|
|
description: |
|
|
Name for the field used to pass the group ID for the setting.
|
|
default_for_system_groups:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
Name of the default group for the setting for system groups.
|
|
|
|
This is non-null only for group-level settings.
|
|
allowed_system_groups:
|
|
type: array
|
|
description: |
|
|
An array of names of system groups to which the setting can
|
|
be set to.
|
|
|
|
If the list is empty, the setting can be set to system groups
|
|
based on the other boolean fields.
|
|
|
|
**Changes**: New in Zulip 8.0 (feature level 225).
|
|
items:
|
|
type: string
|
|
User:
|
|
allOf:
|
|
- $ref: "#/components/schemas/UserBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
delivery_email:
|
|
nullable: true
|
|
email: {}
|
|
full_name: {}
|
|
date_joined: {}
|
|
is_active: {}
|
|
is_owner: {}
|
|
is_admin: {}
|
|
is_guest: {}
|
|
is_billing_admin: {}
|
|
is_bot: {}
|
|
bot_type:
|
|
nullable: true
|
|
bot_owner_id:
|
|
nullable: true
|
|
role: {}
|
|
timezone: {}
|
|
avatar_url:
|
|
nullable: true
|
|
avatar_version: {}
|
|
profile_data: {}
|
|
UserBase:
|
|
type: object
|
|
description: |
|
|
A dictionary containing basic data on a given Zulip user.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the user.
|
|
delivery_email:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The user's real email address. This value will be `null` if you cannot
|
|
access user's real email address. For bot users, this field is always
|
|
set to the real email of the bot, because bot users always have
|
|
`email_address_visibility` set to everyone.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
|
|
present only when `email_address_visibility` was restricted and you had
|
|
access to the user's real email. As of this feature level, this field
|
|
is always present, including the case when `email_address_visibility`
|
|
is set to everyone (and therefore not restricted).
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address of the user or bot.
|
|
|
|
If you do not have permission to view the email address of the target user,
|
|
this will be a fake email address that is usable for the Zulip API but nothing else.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user or bot, used for all display purposes.
|
|
date_joined:
|
|
type: string
|
|
description: |
|
|
The time the user account was created.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user account has been deactivated.
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is an organization owner.
|
|
If true, `is_admin` will also be true.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8).
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is an organization administrator.
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a guest user.
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
is_bot:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a bot or full account.
|
|
bot_type:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
An integer describing the type of bot:
|
|
|
|
- `null` if the user isn't a bot.
|
|
- `1` for a `Generic` bot.
|
|
- `2` for an `Incoming webhook` bot.
|
|
- `3` for an `Outgoing webhook` bot.
|
|
- `4` for an `Embedded` bot.
|
|
bot_owner_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`
|
|
is the user ID of the bot's owner (usually, whoever created the bot).
|
|
|
|
Will be `null` for legacy bots that do not have an owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1). In previous
|
|
versions, there was a `bot_owner` field containing the email
|
|
address of the bot's owner.
|
|
role:
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
description: |
|
|
[Organization-level role](/api/roles-and-permissions) of the user.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The time zone of the user.
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
URL for the user's avatar.
|
|
|
|
Will be `null` if the `client_gravatar`
|
|
query parameter was set to `true`, the current user has access to
|
|
this user's real email address, and this user's avatar is hosted by
|
|
the Gravatar provider (i.e. this user has never uploaded an avatar).
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163), access to a
|
|
user's real email address was a realm-level setting. As of this
|
|
feature level, `email_address_visibility` is a user setting.
|
|
|
|
In Zulip 3.0 (feature level 18), if the client has the
|
|
`user_avatar_url_field_optional` capability, this will be missing at
|
|
the server's sole discretion.
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
Version for the user's avatar. Used for cache-busting requests
|
|
for the user's avatar. Clients generally shouldn't need to use this;
|
|
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
|
|
profile_data:
|
|
$ref: "#/components/schemas/profile_data"
|
|
profile_data:
|
|
type: object
|
|
description: |
|
|
Only present if `is_bot` is false; bots can't have custom profile fields.
|
|
|
|
A dictionary containing custom profile field data for the user. Each entry
|
|
maps the integer ID of a custom profile field in the organization to a
|
|
dictionary containing the user's data for that field. Generally the data
|
|
includes just a single `value` key; for those custom profile fields
|
|
supporting Markdown, a `rendered_value` key will also be present.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
`{id}`: Object with data about what value the user filled in the custom
|
|
profile field with that ID.
|
|
properties:
|
|
value:
|
|
type: string
|
|
description: |
|
|
User's personal value for this custom profile field.
|
|
rendered_value:
|
|
type: string
|
|
description: |
|
|
The `value` rendered in HTML. Will only be present for
|
|
custom profile field types that support Markdown rendering.
|
|
|
|
This user-generated HTML content should be rendered
|
|
using the same CSS and client-side security protections
|
|
as are used for message content.
|
|
JsonResponseBase:
|
|
type: object
|
|
properties:
|
|
result:
|
|
type: string
|
|
JsonSuccess:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
example: {"msg": "", "result": "success"}
|
|
JsonSuccessBase:
|
|
description: |
|
|
**Changes**: As of Zulip 7.0 (feature level 167), if any
|
|
parameters sent in the request are not supported by this
|
|
endpoint, a successful JSON response will include an
|
|
[`ignored_parameters_unsupported`][ignored_params] array.
|
|
|
|
A typical successful JSON response may look like:
|
|
|
|
[ignored_params]: /api/rest-error-handling#ignored-parameters
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result:
|
|
enum:
|
|
- success
|
|
msg:
|
|
type: string
|
|
ignored_parameters_unsupported:
|
|
$ref: "#/components/schemas/IgnoredParametersUnsupported"
|
|
IgnoredParametersSuccess:
|
|
allOf:
|
|
- $ref: "#/components/schemas/IgnoredParametersBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
description: |
|
|
**Changes**: The [`ignored_parameters_unsupported`][ignored_params]
|
|
array was added as a possible return value for all REST API endpoint
|
|
JSON success responses in Zulip 7.0 (feature level 167).
|
|
|
|
Previously, it was added to
|
|
[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings)
|
|
in Zulip 5.0 (feature level 111) and to
|
|
[`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults)
|
|
in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0
|
|
(feature level 78) as a return value for the
|
|
[`PATCH /settings`](/api/update-settings) endpoint.
|
|
|
|
A typical successful JSON response with ignored parameters may look like:
|
|
|
|
[ignored_params]: /api/rest-error-handling#ignored-parameters
|
|
example:
|
|
{
|
|
"ignored_parameters_unsupported":
|
|
["invalid_param_1", "invalid_param_2"],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
IgnoredParametersBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result:
|
|
enum:
|
|
- success
|
|
msg:
|
|
type: string
|
|
ignored_parameters_unsupported:
|
|
$ref: "#/components/schemas/IgnoredParametersUnsupported"
|
|
ApiKeyResponse:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- required:
|
|
- api_key
|
|
- email
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
api_key:
|
|
type: string
|
|
description: |
|
|
The API key that can be used to authenticate as the requested user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The email address of the user who owns the API key.
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the user who owns the API key.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 171).
|
|
example:
|
|
{
|
|
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
|
|
"email": "iago@zulip.com",
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_id": 5,
|
|
}
|
|
CodedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
CodedErrorBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
- code
|
|
properties:
|
|
result:
|
|
enum:
|
|
- error
|
|
msg:
|
|
type: string
|
|
code:
|
|
type: string
|
|
description: |
|
|
A string that identifies the error.
|
|
BadEventQueueIdError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
The string that identifies the invalid event queue.
|
|
example:
|
|
{
|
|
"code": "BAD_EVENT_QUEUE_ID",
|
|
"msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"result": "error",
|
|
}
|
|
InvalidMessageError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
example:
|
|
{
|
|
"msg": "Invalid message(s)",
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
}
|
|
InvalidChannelError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
example:
|
|
{
|
|
"msg": "Invalid channel ID",
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
}
|
|
NonExistingChannelNameError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
stream:
|
|
type: string
|
|
description: |
|
|
The name of the channel that could not be found.
|
|
example:
|
|
{
|
|
"code": "STREAM_DOES_NOT_EXIST",
|
|
"msg": "Channel 'nonexistent' does not exist",
|
|
"result": "error",
|
|
"stream": "nonexistent",
|
|
}
|
|
NonExistingChannelIdError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The channel ID that could not be found.
|
|
example:
|
|
{
|
|
"code": "STREAM_DOES_NOT_EXIST",
|
|
"msg": "Channel with ID '9' does not exist",
|
|
"result": "error",
|
|
"stream_id": 9,
|
|
}
|
|
InvalidApiKeyError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "INVALID_API_KEY",
|
|
"msg": "Invalid API key",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
### Invalid API key
|
|
|
|
A typical failed JSON response for when the API key is invalid.
|
|
InvitationFailedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: boolean
|
|
description: |
|
|
An array of arrays of length 3, where each inner array consists of (a) an email
|
|
address that was skipped while sending invitations, (b) the corresponding error
|
|
message, and (c) a boolean which is `true` when the email address already uses Zulip
|
|
and the corresponding user is deactivated in the organization.
|
|
sent_invitations:
|
|
description: |
|
|
A boolean specifying whether any invitations were sent.
|
|
type: boolean
|
|
daily_limit_reached:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the limit on the number of invitations that can
|
|
be sent in the organization in a day has been reached.
|
|
license_limit_reached:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the organization have enough unused Zulip licenses
|
|
to invite specified number of users.
|
|
MissingArgumentError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
description: |
|
|
### Missing request parameter
|
|
|
|
A typical failed JSON response for when a required request parameter
|
|
is not supplied.
|
|
|
|
The value of `var_name` contains information about the missing parameter.
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
var_name:
|
|
type: string
|
|
description: |
|
|
It contains the information about the missing parameter.
|
|
example:
|
|
{
|
|
"code": "REQUEST_VARIABLE_MISSING",
|
|
"msg": "Missing 'content' argument",
|
|
"result": "error",
|
|
"var_name": "content",
|
|
}
|
|
IncompatibleParametersError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
description: |
|
|
### Incompatible request parameters
|
|
|
|
A typical failed JSON response for when two or more, optional
|
|
parameters are supplied that are incompatible with each other.
|
|
|
|
The value of `parameters` in the response is string containing
|
|
the parameters, separated by commas, that are incompatible.
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
parameters:
|
|
type: string
|
|
description: |
|
|
A string containing the parameters, separated by commas,
|
|
that are incompatible.
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Unsupported parameter combination: object_id, object_name",
|
|
"result": "error",
|
|
"parameters": "object_id, object_name",
|
|
}
|
|
UserNotAuthorizedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User not authorized for this query",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
### User not authorized for query
|
|
|
|
A typical failed JSON response for when the user is not authorized for
|
|
a query.
|
|
UserDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "USER_DEACTIVATED",
|
|
"msg": "Account is deactivated",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
### User account deactivated
|
|
|
|
A typical failed json response for when user's account is deactivated.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 76), these errors use the
|
|
HTTP 401 status code. Before this feature level, they used the HTTP 403
|
|
status code.
|
|
RateLimitedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
description: |
|
|
### Rate limit exceeded
|
|
|
|
A typical failed JSON response for when a rate limit is exceeded.
|
|
Zulip sets a few [HTTP response headers][rate-limit-headers]
|
|
to help with preventing rate limit errors.
|
|
|
|
The value of `retry-after` in the response indicates how many
|
|
seconds the client must wait before making additional requests.
|
|
|
|
**Changes**: Before Zulip 4.0 (feature level 36), the `code` key
|
|
was not present in rate limit errors.
|
|
|
|
[rate-limit-headers]: /api/http-headers#rate-limiting-response-headers
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
retry-after:
|
|
type: integer
|
|
description: |
|
|
How many seconds the client must wait before making
|
|
additional requests.
|
|
example:
|
|
{
|
|
"code": "RATE_LIMIT_HIT",
|
|
"msg": "API usage exceeded rate limit",
|
|
"result": "error",
|
|
"retry-after": 28.706807374954224,
|
|
}
|
|
RealmDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "REALM_DEACTIVATED",
|
|
"msg": "This organization is deactivated",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
### Realm deactivated
|
|
|
|
A typical failed json response for when user's organization is deactivated.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 76), these errors use the
|
|
HTTP 401 status code. Before this feature level, they used the HTTP 403
|
|
status code.
|
|
InvalidPushDeviceTokenError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "INVALID_PUSH_DEVICE_TOKEN",
|
|
"msg": "Device not recognized",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
## Invalid push device token
|
|
|
|
A typical failed JSON response for when the push device token is not
|
|
recognized by the Zulip server:
|
|
InvalidRemotePushDeviceTokenError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "INVALID_REMOTE_PUSH_DEVICE_TOKEN",
|
|
"msg": "Device not recognized by the push bouncer",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
## Invalid push device token
|
|
|
|
A typical failed JSON response for when the push device token is not recognized
|
|
by the push notification bouncer:
|
|
Event_types:
|
|
description: |
|
|
A JSON-encoded array indicating which types of events you're interested
|
|
in. Values that you might find useful include:
|
|
|
|
- **message** (messages)
|
|
- **subscription** (changes in your subscriptions)
|
|
- **realm_user** (changes to users in the organization and
|
|
their properties, such as their name).
|
|
|
|
If you do not specify this parameter, you will receive all
|
|
events, and have to filter out the events not relevant to
|
|
your client in your client code. For most applications, one
|
|
is only interested in messages, so one specifies:
|
|
`"event_types": ["message"]`
|
|
|
|
Event types not supported by the server are ignored, in order to simplify
|
|
the implementation of client apps that support multiple server versions.
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["message"]
|
|
Narrow:
|
|
description: |
|
|
A JSON-encoded array of arrays of length 2 indicating the
|
|
[narrow filter(s)](/api/construct-narrow) for which you'd
|
|
like to receive events for.
|
|
|
|
For example, to receive events for direct messages (including
|
|
group direct messages) received by the user, one can use
|
|
`"narrow": [["is", "dm"]]`.
|
|
|
|
Unlike the API for [fetching messages](/api/get-messages),
|
|
this narrow parameter is simply a filter on messages that the
|
|
user receives through their channel subscriptions (or because
|
|
they are a recipient of a direct message).
|
|
|
|
This means that a client that requests a `narrow` filter of
|
|
`[["channel", "Denmark"]]` will receive events for new messages
|
|
sent to that channel while the user is subscribed to that
|
|
channel. The client will not receive any message events at all
|
|
if the user is not subscribed to `"Denmark"`.
|
|
|
|
Newly created bot users are not usually subscribed to any
|
|
channels, so bots using this API need to be
|
|
[subscribed](/api/subscribe) to any channels whose messages
|
|
you'd like them to process using this endpoint.
|
|
|
|
See the `all_public_streams` parameter for how to process all
|
|
public channel messages in an organization.
|
|
|
|
**Changes**: See [changes section](/api/construct-narrow#changes)
|
|
of search/narrow filter documentation.
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
type: string
|
|
default: []
|
|
example: [["channel", "Denmark"]]
|
|
AllPublicChannels:
|
|
description: |
|
|
Whether you would like to request message events from all public
|
|
channels. Useful for workflow bots that you'd like to see all new messages
|
|
sent to public channels. (You can also subscribe the user to private channels).
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
RequiredContent:
|
|
description: |
|
|
The content of the message.
|
|
|
|
Clients should use the `max_message_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum message size.
|
|
type: string
|
|
example: Hello
|
|
OptionalContent:
|
|
description: |
|
|
The updated content of the target message.
|
|
|
|
Clients should use the `max_message_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum message size.
|
|
|
|
Note that a message's content and channel cannot be changed at the
|
|
same time, so sending both `content` and `stream_id` parameters will
|
|
throw an error.
|
|
type: string
|
|
example: Hello
|
|
ChannelPostPolicy:
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the channel.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
type: integer
|
|
default: 1
|
|
example: 2
|
|
HistoryPublicToSubscribers:
|
|
description: |
|
|
Whether the channel's message history should be available to
|
|
newly subscribed members, or users can only access messages
|
|
they actually received while subscribed to the channel.
|
|
|
|
Corresponds to the [shared history](/help/channel-permissions)
|
|
option in documentation.
|
|
type: boolean
|
|
example: false
|
|
Principals:
|
|
description: |
|
|
A list of user IDs (preferred) or Zulip API email
|
|
addresses of the users to be subscribed to or unsubscribed
|
|
from the channels specified in the `subscriptions` parameter. If
|
|
not provided, then the requesting user/bot is subscribed.
|
|
|
|
**Changes**: The integer format is new in Zulip 3.0 (feature level 9).
|
|
oneOf:
|
|
- type: array
|
|
items:
|
|
type: string
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
example: ["ZOE@zulip.com"]
|
|
ReactionType:
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
If an API client is adding/removing a vote on an existing reaction,
|
|
it should pass this parameter using the value the server provided
|
|
for the existing reaction for specificity. Supported values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: In Zulip 3.0 (feature level 2), this parameter became
|
|
optional for [custom emoji](/help/custom-emoji);
|
|
previously, this endpoint assumed `unicode_emoji` if this
|
|
parameter was not specified.
|
|
type: string
|
|
example: "unicode_emoji"
|
|
EmojiCode:
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
|
|
For most API clients, you won't need this, but it's important
|
|
for Zulip apps to handle rare corner cases when
|
|
adding/removing votes on an emoji reaction added previously by
|
|
another user.
|
|
|
|
If the existing reaction was added when the Zulip server was
|
|
using a previous version of the emoji data mapping between
|
|
Unicode codepoints and human-readable names, sending the
|
|
`emoji_code` in the data for the original reaction allows the
|
|
Zulip server to correctly interpret your upvote as an upvote
|
|
rather than a reaction with a "different" emoji.
|
|
type: string
|
|
example: "1f419"
|
|
MessageRetentionDays:
|
|
description: |
|
|
Number of days that messages sent to this channel will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). Two special string format
|
|
values are supported:
|
|
|
|
- `"realm_default"`: Return to the organization-level setting.
|
|
- `"unlimited"`: Retain messages forever.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 91), retaining
|
|
messages forever was encoded using `"forever"` instead of
|
|
`"unlimited"`.
|
|
|
|
New in Zulip 3.0 (feature level 17).
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: "20"
|
|
CanRemoveSubscribersGroup:
|
|
allOf:
|
|
- $ref: "#/components/schemas/GroupSettingValue"
|
|
- description: |
|
|
A [group-setting value][setting-values] defining the set of users
|
|
who have permission to remove subscribers from this channel.
|
|
|
|
Note that a user who is a member of the specified user group must
|
|
also [have access](/help/channel-permissions) to the channel in
|
|
order to unsubscribe others.
|
|
|
|
**Changes**: Prior to Zulip 10.0 (feature level 320), this value was
|
|
always the integer ID of a system group.
|
|
|
|
Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group`
|
|
setting was named `can_remove_subscribers_group_id`.
|
|
|
|
New in Zulip 6.0 (feature level 142).
|
|
|
|
[setting-values]: /api/group-setting-values
|
|
LinkifierPattern:
|
|
description: |
|
|
The [Python regular
|
|
expression](https://docs.python.org/3/howto/regex.html) that should
|
|
trigger the linkifier.
|
|
type: string
|
|
example: "#(?P<id>[0-9]+)"
|
|
LinkifierURLTemplate:
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
|
|
compliant URL template used for the link.
|
|
If you used named groups in `pattern`, you can insert their
|
|
content here with `{name_of_group}`.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced
|
|
the `url_format_string` parameter, which was a format string in which
|
|
named groups' content could be inserted with `%(name_of_group)s`.
|
|
type: string
|
|
example: https://github.com/zulip/zulip/issues/{id}
|
|
|
|
###################
|
|
# Shared responses
|
|
###################
|
|
responses:
|
|
SimpleSuccess:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
SuccessIgnoredParameters:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/IgnoredParametersSuccess"
|
|
|
|
################
|
|
# Shared request bodies
|
|
################
|
|
requestBodies:
|
|
UpdateUser:
|
|
required: false
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
full_name:
|
|
description: |
|
|
The user's full name.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 5.0 (feature level 106).
|
|
type: string
|
|
example: NewName
|
|
role:
|
|
description: |
|
|
New [role](/api/roles-and-permissions) for the user. Roles are encoded as:
|
|
|
|
- Organization owner: 100
|
|
- Organization administrator: 200
|
|
- Organization moderator: 300
|
|
- Member: 400
|
|
- Guest: 600
|
|
|
|
Only organization owners can add or remove the owner role.
|
|
|
|
The owner role cannot be removed from the only organization owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous
|
|
pair of `is_admin` and `is_guest` boolean parameters. Organization moderator
|
|
role added in Zulip 4.0 (feature level 60).
|
|
type: integer
|
|
example: 400
|
|
profile_data:
|
|
description: |
|
|
A dictionary containing the updated custom profile field data for the user.
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
[{"id": 4, "value": "0"}, {"id": 5, "value": "1909-04-05"}]
|
|
new_email:
|
|
description: |
|
|
New email address for the user. Requires the user making the request
|
|
to be an organization owner and additionally have the `.can_change_user_emails`
|
|
special permission.
|
|
|
|
**Changes**: New in Zulip 10.0 (feature level 285).
|
|
type: string
|
|
example: username@example.com
|
|
encoding:
|
|
role:
|
|
contentType: application/json
|
|
profile_data:
|
|
contentType: application/json
|
|
|
|
####################
|
|
# Shared parameters
|
|
####################
|
|
parameters:
|
|
UserGroupId:
|
|
name: user_group_id
|
|
in: path
|
|
description: |
|
|
The ID of the target user group.
|
|
schema:
|
|
type: integer
|
|
example: 35
|
|
required: true
|
|
QueueId:
|
|
name: queue_id
|
|
in: query
|
|
description: |
|
|
The ID of an event queue that was previously registered via
|
|
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
|
|
schema:
|
|
type: string
|
|
example: fb67bf8a-c031-47cc-84cf-ed80accacda8
|
|
required: true
|
|
ChannelIdInPath:
|
|
name: stream_id
|
|
in: path
|
|
description: |
|
|
The ID of the channel to access.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
ClientGravatar:
|
|
name: client_gravatar
|
|
in: query
|
|
description: |
|
|
Whether the client supports computing gravatars URLs. If
|
|
enabled, `avatar_url` will be included in the response only
|
|
if there is a Zulip avatar, and will be `null` for users who
|
|
are using gravatar as their avatar. This option
|
|
significantly reduces the compressed size of user data,
|
|
since gravatar URLs are long, random strings and thus do not
|
|
compress well. The `client_gravatar` field is set to `true` if
|
|
clients can compute their own gravatars.
|
|
|
|
**Changes**: The default value of this parameter was `false`
|
|
prior to Zulip 5.0 (feature level 92).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
MessageId:
|
|
name: message_id
|
|
in: path
|
|
description: |
|
|
The target message's ID.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
UserId:
|
|
name: user_id
|
|
in: path
|
|
description: |
|
|
The target user's ID.
|
|
schema:
|
|
type: integer
|
|
example: 12
|
|
required: true
|
|
MutedUserId:
|
|
name: muted_user_id
|
|
in: path
|
|
description: |
|
|
The ID of the user to mute/unmute.
|
|
|
|
**Changes**: Before Zulip 8.0 (feature level 188), bot users could not
|
|
be muted/unmuted, and specifying a bot user's ID returned an error response.
|
|
schema:
|
|
type: integer
|
|
example: 10
|
|
required: true
|
|
IncludeSubscribers:
|
|
name: include_subscribers
|
|
in: query
|
|
description: |
|
|
Whether each returned channel object should include a `subscribers`
|
|
field containing a list of the user IDs of its subscribers.
|
|
|
|
(This may be significantly slower in organizations with
|
|
thousands of users subscribed to many channels.)
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
IncludeCustomProfileFields:
|
|
name: include_custom_profile_fields
|
|
in: query
|
|
description: |
|
|
Whether the client wants [custom profile field](/help/custom-profile-fields)
|
|
data to be included in the response.
|
|
|
|
**Changes**: New in Zulip 2.1.0. Previous versions do not offer these
|
|
data via the API.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
DirectMemberOnly:
|
|
name: direct_member_only
|
|
in: query
|
|
description: |
|
|
Whether to consider only the direct members of user group and not members
|
|
of its subgroups. Default is `false`.
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
required: false
|