Messages

A message is something a member says in a conversation. It can be text, a reference to a file, or a note from your backend, and it can carry replies, mentions and reactions. This page covers what a message is and the rules for sending, editing and deleting one.

Types

`message_type`	Meaning	Who may send it
`TEXT`	A text message. The default.	Members, and your backend on behalf of a member
`FILE`	A message with attachments. The default when `attachments` is present.	Same
`SYSTEM`	A SYSTEM message: no sender, for notices such as “Coaching has ended”.	Backend clients only

A message needs a body or at least one attachment. The body is at most 10,000 characters, or the call fails with 400 body_too_long.

Chat permission: messages.sendUser scope: chat:accessMachine scope (any of): chat:messages.send

Sending to an archived conversation answers 422 conversation_archived. Sending is rate limited per user: 30 messages per 10 s per user.

Who the sender is

A user’s message has sender_user_id set to that user. Your backend sends on behalf of a member with actor_user_id, and the message then carries your client’s id in sender_client_id. A SYSTEM message has no sender. See Machine scopes.

Attachments are references

Chat stores no files. An attachment is a reference to a file kept on a separate file platform:

{ "file_id": "file-8f3a", "name": "plan.pdf", "mime_type": "application/pdf", "size": 48213 }

You upload the file elsewhere, then send its file_id with its name, mime_type and size. A message holds at most 10 attachments, or the call fails with 400 too_many_attachments. Chat returns the same fields. The url field is present but null.

Replies and mentions

Replies. Set reply_to_message_id to a message of the same conversation. Anything else answers 422 invalid_reply.
Mentions. Send mentioned_user_ids. Chat keeps only users who are active members of the conversation and returns them as mentioned_user_ids. In a channel, mentions decide who gets a push; see Push notifications.

Reactions

A member reacts to a message with an emoji and can take the reaction back. A message returns a summary per emoji: emoji, count and reacted_by_me. Reactions need messages.read and membership, and they are for users only. A machine gets 400 user_required. You cannot react to a deleted message.

Edit and delete

Edit. A user edits their own message with messages.update. A holder of messages.delete can also edit other members’ messages, because Chat treats that permission as moderation. Grant it only to people you trust to change what others wrote. The message gets status: EDITED and edited_at. A deleted message cannot be edited.
Delete. A user deletes their own message with messages.update. A holder of messages.delete can delete other members’ messages as a moderator, and Chat audits that. A backend client cannot delete or edit messages.
Tombstones. A deleted message stays in the list as a tombstone: status: DELETED, an empty body and no attachments.

Read state and typing

Read state. A user marks a conversation read up to a message, by default the latest. The conversation’s has_unread flag follows it. A user’s own messages count as read for them.
Typing. Typing is a signal, never stored. Chat delivers it to the other members as a typing event and forgets it.

Both are for users with messages.read who are members. Machines get user_required.

Reading messages

Messages list newest first and page with a cursor; see Pagination. A user reads a conversation they belong to, or a PUBLIC channel. A backend client reads any conversation of its application with chat:conversations.read.