Zulip webhooks API
The webhooks API from Zulip — 1 operation(s) for webhooks.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication webhooks 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:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: webhooks
paths:
/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 [Zulip-flavored Markdown](/help/format-your-message-using-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: {}
last_moved_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.
See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.
'
example:
data: '@**Outgoing webhook test** Zulip is the world’s 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’s most productive group chat!</p>
sender_id: 5
stream_id: 5
content: '@**Outgoing webhook test** Zulip is the world’s 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
components:
schemas:
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`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n"
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), which
deprecated the `user` object.
'
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.
When `apply_markdown` is set, it will be in HTML format.
See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.
'
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.
See the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.
'
display_recipient:
description: 'Data on the recipient of the message. Will be one of the following:
'
oneOf:
- type: string
description: 'The name of the channel the message was received in.
'
- type: array
description: 'An array of dictionaries containing basic data on the users who
received the message.
'
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.
'
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`.
See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.
'
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 moved,
or if [viewing message edit history][edit-history-access]
is not allowed in the organization.
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`.
[edit-history-access]: /help/restrict-message-edit-history-access
**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''s content was last edited, in
UTC seconds.
Not present if the message''s content has never been edited.
Clients should use this field, rather than parsing the `edit_history`
array, to display an indicator that the message has been edited.
**Changes**: Prior to Zulip 10.0 (feature level 365), this was the
time when the message was last edited or moved.
'
last_moved_timestamp:
type: integer
description: 'The UNIX timestamp for when the message was last moved to a different
channel or topic, in UTC seconds.
Not present if the message has never been moved, or if the only topic
moves for the message are [resolving or unresolving](/help/resolve-a-topic)
the message''s topic.
Clients should use this field, rather than parsing the `edit_history`
array, to display an indicator that the message has been moved.
**Changes**: New in Zulip 10.0 (feature level 365). Previously,
parsing the `edit_history` array was required in order to correctly
display moved message indicators.
'
reactions:
type: array
description: 'Data on any [reactions](/help/emoji-reactions) to the message,
ordered chronologically from oldest to newest reaction.
**Changes**: In Zulip 10.0 (feature level 328), the deprecated `user`
object was removed from the data for each reaction. It contained the
following information about the user who added the reaction: `id`,
`email`, `full_name` and `is_mirror_dummy`.
'
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.
**Changes**: In Zulip 12.0 (feature level 482),
`recipient_id` in 1:1 direct messages changed to a new
value; it still has the semantics of "the 1:1 conversation
with a specific user," but the raw value changed due to
internal changes.
Before Zulip 10.0 (feature level 327), `recipient_id`
was the same across all incoming 1:1 direct messages. Now, each
incoming message uniquely shares a `recipient_id` with outgoing
messages in the same conversation.
'
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.
For clients that don''t support the `empty_topic_name` [client capability][client-capabilities],
the empty string value is replaced with the value of `realm_empty_topic_display_name`
found in the [POST /register](/api/register-queue) response, for channel messages.
**Changes**: Before Zulip 10.0 (feature level 334), `empty_topic_name`
client capability didn''t exist and empty string as the topic name for
channel messages wasn''t allowed.
[client-capabilities]: /api/register-queue#parameter-client_capabilities
'
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"`.
'
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.
'