paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 05:53:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

api docs: Expand further API documentation on update_message event.

Browse Source 
These details clarify the roles of `message_id` and `message_ids`, and
should help a great deal in helping clients correctly implement this
critical API endpoint.
This commit is contained in:
Tim Abbott
2021-04-29 08:52:47 -07:00
parent 339b50fa46
commit 8295bb9181
1 changed files with 69 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
zerver/openapi/zulip.yaml
View File

@@ -1800,56 +1800,72 @@ paths:
description: | description: |
The ID of the message which was edited. The ID of the message which was edited.
This field is used for content edits. For stream and topic edits, use the This field should be used to apply content edits to the client's
`message_ids` field instead. cached message history. If the stream 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: message_ids:
type: array type: array
items: items:
type: integer type: integer
description: | description: |
For edits changing the stream or topic of multiple messages, The list of IDs of messages to which any stream or topic changes
the list of IDs of other messages to be moved as well. encoded in this event should be applied.
The messages are guaranteed to have all been previously in the These messages are guaranteed to have all been previously sent
same stream and topic. to stream `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).
Any content change updates only the message indicated in `message_id`. 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 stream and
topic.
Content changes should be applied only to the single message
indicated by `message_id`.
edit_timestamp: edit_timestamp:
type: integer type: integer
description: | description: |
The timestamp when the message was edited. The time when this message edit operation was processed by the
server.
stream_name: stream_name:
type: string type: string
description: | description: |
Only present if the message was originally sent to a stream. Only present if the message was originally sent to a stream.
The name of the stream that the message was sent to. The name of the stream that the message was sent to. Clients
are recommended to use the `stream_id` field instead.
stream_id: stream_id:
type: integer type: integer
description: | description: |
Only present if the message was originally sent to a stream. Only present if the message was originally sent to a stream.
The ID of the stream that the message was sent to. The pre-edit stream for all of the messages with IDs in
`message_ids`.
new_stream_id: new_stream_id:
type: integer type: integer
description: | description: |
Note: Only present if message(s) were moved to a different stream. Note: Only present if message(s) were moved to a different stream.
The ID of the stream that the message was moved to. The post-edit stream for all of the messages with IDs in
`message_ids`.
propagate_mode: propagate_mode:
type: string type: string
description: | description: |
Which message(s) should be edited: just the one indicated in The choice the editing user made about which messages should be
`message_id`, messages in the same topic that had been sent after this affected by a stream/topic edit: just the one indicated in
one, or all of them. `message_id`, messages in the same topic that had been sent
after this one, or all messages in that topic.
This parameter should be used to decide whether to change This parameter should be used to decide whether to change
navigation and compose box state in response to the edit. For navigation and compose box state in response to the edit. For
example, if the user was previously in topic narrow, and the example, if the user was previously in topic narrow, and the
topic was edited with `change_later` or `change_all`, the Zulip topic was edited with `change_later` or `change_all`, the Zulip
webapp will automatically navigate to the new topic narrow. webapp will automatically navigate to the new topic narrow.
Additionally, a message being composed to the old topic should Similarly, a message being composed to the old topic should
have its recipient automatically moved to the new topic. have its recipient changed to the new topic.
This navigation makes it much more convenient to move content This navigation makes it much more convenient to move content
between topics without disruption or messages continuing between topics without disruption or messages continuing
@@ -1861,12 +1877,19 @@ paths:
orig_subject: orig_subject:
type: string type: string
description: | description: |
The original topic of the message. Only present if the topic of the message The pre-edit topic for all of the messages with IDs in
was changed. `message_ids`.
Only present if this event moved messages to a different
topic.
subject: subject:
type: string type: string
description: | description: |
The current topic of the message following the edit. The post-edit topic for all of the messages with IDs in
`message_ids`.
Only present if this event moved messages to a different
topic.
topic_links: topic_links:
type: array type: array
items: items:
@@ -1885,7 +1908,11 @@ paths:
Data on any links to be included in the `topic` Data on any links to be included in the `topic`
line (these are generated by line (these are generated by
[custom linkification filter](/help/add-a-custom-linkifier) [custom linkification filter](/help/add-a-custom-linkifier)
that match content in the message's topic.) that match content in the message's topic.), corresponding
to the post-edit topic.
Only present if this event moved messages to a different
topic.
**Changes**: This field contained a list of urls before **Changes**: This field contained a list of urls before
Zulip 4.0 (feature level 46). Zulip 4.0 (feature level 46).
@@ -1897,34 +1924,47 @@ paths:
orig_content: orig_content:
type: string type: string
description: | description: |
The original Markdown content of the message, before this edit. The original content of the message with ID `message_id`
immediately prior to this edit, in the original markdown.
orig_rendered_content: orig_rendered_content:
type: string type: string
description: | description: |
The original content of the message, before this edit, rendered as HTML. The original content of the message with ID `message_id`
immediately prior to this edit, rendered as HTML.
prev_rendered_content_version: prev_rendered_content_version:
type: integer type: integer
description: | description: |
The Markdown processor version number for the pre-edit message. The Markdown processor version number for the pre-edit message.
Clients should ignore this field.
content: content:
type: string type: string
description: | description: |
The new content of the message, in the original Markdown. Applies only The new content of the message with ID `message_id`, in the
to the message indicated by `message_id`, not all messages in `message_ids`. original Markdown.
rendered_content: rendered_content:
type: string type: string
description: | description: |
The new content of the message, rendered in HTML. The new content of the message with ID `message_id`,
rendered in HTML.
is_me_message: is_me_message:
type: boolean type: boolean
description: | description: |
Whether the message is now a [/me status message][status-messages]. 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
flags: flags:
type: array type: array
description: | description: |
The user's personal [message flags][message-flags] for the message The user's personal [message flags][message-flags] for the
following the edit. The client should compare these to the original message with ID `message_id` following the edit.
flags to identify cases where a mention was added by 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.
[message-flags]: /api/update-message-flags#available-flags
items: items:
type: string type: string
example: example: