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:

@Outgoing webhook test Zulip is the world’s most productive group chat!

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. '