Types

The messages and enums that calls and events share. In JSON (protojson) field names are lowerCamelCase, 64-bit numbers are strings, and enums are their names. Tools can read the same types from schema.json.

MemberKind

Value	Number	Notes
`MEMBER_KIND_UNSPECIFIED`	0
`MEMBER_KIND_HUMAN`	1
`MEMBER_KIND_BOT`	2

MemberRole

Value	Number	Notes
`MEMBER_ROLE_UNSPECIFIED`	0
`MEMBER_ROLE_MEMBER`	1
`MEMBER_ROLE_MODERATOR`	2
`MEMBER_ROLE_ADMIN`	3
`MEMBER_ROLE_OWNER`	4

Presence

Value	Number	Notes
`PRESENCE_UNSPECIFIED`	0
`PRESENCE_ONLINE`	1
`PRESENCE_AWAY`	2
`PRESENCE_OFFLINE`	3

Member

Field	Type	Notes
`id`	`string`	UUIDv7, local to this server
`kind`	MemberKind
`role`	MemberRole
`username`	`string`	unique on this server
`display_name`	`string`
`avatar_url`	`string`	may be empty
`bio`	`string`
`presence`	Presence
`joined_at_ms`	`int64`
`status_text`	`string`	short custom status, may be empty
`status_emoji`	`string`
`role_ids`	repeated `string`	custom roles (visibility only), see Role

Role

A custom role, made by admins. Roles only decide which text channels a member can see (Channel.role_ids). MemberRole still decides permissions; call that one "Permission" in the UI and these "Roles".

Field	Type	Notes
`id`	`string`
`name`	`string`	unique, case-insensitive
`color`	`string`	"#rrggbb" or empty
`position`	`int32`	sort order, low first

ChannelMode

How members get into text channels. Private channels and DMs keep their explicit member lists in both modes.

Value	Number	Notes
`CHANNEL_MODE_UNSPECIFIED`	0
`CHANNEL_MODE_ROLES`	1	Discord-like: you are in every text channel you can see
`CHANNEL_MODE_OPT_IN`	2	Slack-like: browse the channels you can see, join and leave them

ChannelKind

Value	Number	Notes
`CHANNEL_KIND_UNSPECIFIED`	0
`CHANNEL_KIND_TEXT`	1	every member can see it, unless role_ids limits it
`CHANNEL_KIND_PRIVATE`	2	invite only
`CHANNEL_KIND_DM`	3	direct message, 2+ members

Channel

Field	Type	Notes
`id`	`string`
`kind`	ChannelKind
`name`	`string`	empty for DMs
`topic`	`string`
`category`	`string`	sidebar section, e.g. "General"; empty = none
`position`	`int32`	sort order inside the category
`member_ids`	repeated `string`	set for DM and PRIVATE channels
`created_at_ms`	`int64`
`last_message_seq`	`int64`	seq of the newest message, 0 if none
`role_ids`	repeated `string`	TEXT only. Empty: every member can see the channel. Otherwise only members with one of these roles (and admins and the owner) can.
`is_default`	`bool`	TEXT only: OPT_IN mode joins new members to it
`member_count`	`int32`	set by BrowseChannels only; 0 elsewhere
`header_image`	Attachment	optional image behind the channel header

Attachment

Field	Type	Notes
`id`	`string`
`name`	`string`
`content_type`	`string`
`size`	`int64`
`url`	`string`	relative to the server base URL
`width`	`int32`	images only
`height`	`int32`

Reaction

Field	Type	Notes
`emoji`	`string`	unicode emoji or ":shortcode:"
`member_ids`	repeated `string`

Message

Field	Type	Notes
`id`	`string`
`channel_id`	`string`
`author_id`	`string`
`text`	`string`	markdown subset: bold, italic, code, links, mentions <@member_id>
`created_at_ms`	`int64`
`edited_at_ms`	`int64`	0 if never edited
`deleted`	`bool`
`thread_root_id`	`string`	set when this message is a thread reply
`reply_count`	`int32`	on a thread root
`last_reply_at_ms`	`int64`
`reactions`	repeated Reaction
`attachments`	repeated Attachment
`client_id`	`string`	echo of SendMessageRequest.client_id, for optimistic UI
`seq`	`int64`	event seq that last changed this message (edits, reactions, replies bump it)
`created_seq`	`int64`	seq of message_created; never changes. Compare this with last_read_seq.

ReadState

Field	Type	Notes
`channel_id`	`string`
`last_read_seq`	`int64`
`unread_count`	`int32`
`mention_count`	`int32`

TypingEvent

Field	Type	Notes
`channel_id`	`string`
`member_id`	`string`
`thread_root_id`	`string`

PresenceEvent

Field	Type	Notes
`member_id`	`string`
`presence`	Presence

PresenceBatch

Many presence changes at once, the latest per member. The server sends this instead of single presence events when several are waiting (a reconnect burst after a restart).

Field	Type	Notes
`changes`	repeated PresenceEvent

Event

Field	Type	Notes
`seq`	`int64`	0 for ephemeral events (typing, presence, heartbeat)
`at_ms`	`int64`
`message_created`	Message	One of `kind`.
`message_updated`	Message	One of `kind`. edits, reactions, reply counts
`message_deleted`	Message	One of `kind`.
`channel_created`	Channel	One of `kind`.
`channel_updated`	Channel	One of `kind`.
`channel_deleted`	`string`	One of `kind`. channel id
`member_joined`	Member	One of `kind`.
`member_updated`	Member	One of `kind`.
`member_left`	`string`	One of `kind`. member id
`read_state`	ReadState	One of `kind`. my own read state, from another device
`typing`	TypingEvent	One of `kind`. ephemeral
`presence`	PresenceEvent	One of `kind`. ephemeral
`heartbeat`	`bool`	One of `kind`. ephemeral, every 25s keeps proxies open
`resync`	`bool`	One of `kind`. client must call GetState
`role_updated`	Role	One of `kind`. created or changed
`role_deleted`	`string`	One of `kind`. role id; drop it from members and channels
`channel_mode_changed`	ChannelMode	One of `kind`.
`server_updated`	`bool`	One of `kind`. description, banner or icon changed; call GetServerInfo
`emoji_changed`	`bool`	One of `kind`. custom emoji added or deleted; refetch GET /emoji
`presence_batch`	PresenceBatch	One of `kind`. ephemeral; apply each change like presence
`plugins_changed`	`bool`	One of `kind`. a plugin was installed, enabled, disabled or deleted; admins call ListPlugins
`member_blocked`	`string`	One of `kind`. member id; I blocked them (from any of my devices)
`member_unblocked`	`string`	One of `kind`. member id; I unblocked them
`member_muted`	`string`	One of `kind`. member id; I muted them (from any of my devices)
`member_unmuted`	`string`	One of `kind`. member id; I unmuted them

LinkPreview

Field	Type	Notes
`url`	`string`	the link as written in the message
`title`	`string`
`description`	`string`
`site_name`	`string`
`image_url`	`string`	relative to the server base URL; "" if none

Ban

A banned login. The member row stays, so member.id keeps working.

Field	Type	Notes
`member`	Member	the profile they had when banned
`banned_by`	`string`	member id
`banned_at_ms`	`int64`

Report

Field	Type	Notes
`id`	`string`
`message`	Message	copy at report time: id, channel_id, author_id, text, created_at_ms, thread_root_id
`dm`	`bool`	the message is in a DM; moderators cannot open it
`author`	Member	who wrote the message (may have left)
`reporter`	Member
`note`	`string`
`reported_at_ms`	`int64`

Invite

Field	Type	Notes
`code`	`string`	10 characters, A-Z and 2-7
`created_by`	`string`	member id
`created_at_ms`	`int64`
`expires_at_ms`	`int64`	0 = never
`max_uses`	`int32`	0 = no limit
`uses`	`int32`	joins it allowed so far

CustomEmoji

Field	Type	Notes
`name`	`string`	1 to 62 of a-z, 0-9, - and _; unique on this server
`url`	`string`	relative to the server base URL; never changes, cache forever

ListEmojiResponse

Field	Type	Notes
`emoji`	repeated CustomEmoji	sorted by name

EmojiUploadStatus

Value	Number	Notes
`EMOJI_UPLOAD_STATUS_UNSPECIFIED`	0
`EMOJI_UPLOAD_STATUS_ADDED`	1
`EMOJI_UPLOAD_STATUS_EXISTS`	2	skipped: the name is taken
`EMOJI_UPLOAD_STATUS_REJECTED`	3	see error

EmojiUploadResult

Field	Type	Notes
`file`	`string`	the file name, or its path inside a zip
`name`	`string`	emoji name made from the file name
`status`	EmojiUploadStatus
`error`	`string`	why it was rejected

UploadEmojiResponse

Field	Type	Notes
`results`	repeated EmojiUploadResult

Plugin

A JavaScript plugin in the plugins folder of the data directory. name is also its bot's username.

Field	Type	Notes
`name`	`string`
`enabled`	`bool`
`running`	`bool`	loaded and taking hooks
`error`	`string`	why it did not load, or its last hook failure
`bot_id`	`string`	"" until it has loaded once

View this page as Markdown · Glossary · API schema.json · openapi.json