types

Data types shared by every interface.

Types

snowflake

type

A Discord ID. Snowflakes encode their creation time in the upper 42 bits, as milliseconds since 2015-01-01T00:00:00Z.

Alias of u64.

log-level

enum

Severity of a log message.

Case	Description
trace
debug
info
warn
error

setting-value

variant

The value of a plugin setting.

Case	Payload	Description
boolean	bool
integer	s64
number	f64
text	string

select-option

record

One choice of a select setting or of a command option.

Field	Type	Description
label	string	Shown to the user.
value	string	Stored as the setting value or passed as the command argument.

slider

record

A number setting shown as a slider.

Field	Type	Description
min	f64
max	f64
step	option<f64>	Snap interval. none lets the slider move freely.
markers	list<f64>	Values to mark on the slider track.

setting-kind

variant

How a setting is stored and shown in the settings UI. The setting’s default must use the matching setting-value case: text for text and select, number for number and slider.

Case	Payload	Description
boolean
integer
number
text
select	list<select-option>
slider	slider
hidden		Stored but never shown. Use it for plugin data the user should not edit directly, typically JSON in a text value.

setting

record

A setting declared in plugin-info.

Field	Type	Description
key	string	Identifies the setting in host.get-setting and host.set-setting.
description	string
kind	setting-kind
default	setting-value	Returned by host.get-setting until the user changes the setting.
restart-needed	bool	Show a restart prompt when the user changes this setting.

command-option-kind

enum

The type of a slash command option.

Case	Description
text
integer
number
boolean
user
channel
role
mentionable
attachment

command-option

record

Field	Type	Description
name	string
description	string
kind	command-option-kind
required	bool
choices	list<select-option>	Restricts the option to these values. Empty allows any value.

command

record

A slash command declared in plugin-info. Invocations arrive as event.command.

Field	Type	Description
name	string	Name without the leading slash.
description	string
options	list<command-option>

hook

enum

A hook the plugin implements. PhoenixCord only calls the plugin functions whose hook is listed in plugin-info.hooks.

Case	Description
message-pre-send	plugin.pre-send
message-pre-edit	plugin.pre-edit
message-accessories	plugin.message-accessories
message-decorations	plugin.message-decorations
message-popover-buttons	plugin.message-popover-buttons
chat-bar-buttons	plugin.chat-bar-buttons
context-menu	plugin.context-menu
profile-sections	plugin.profile-sections
user-badges	plugin.user-badges
member-decorations	plugin.member-decorations
server-list-elements	plugin.server-list-elements
settings-panel	plugin.settings-panel

event-kind

enum

A kind of client event a plugin can subscribe to in plugin-info.events. Timer, HTTP, Discord request, UI action, command and setting events are always delivered to the plugin that caused them and need no subscription.

Case	Description
ready
logout
message-created
message-updated
message-deleted
typing-started
presence-updated
voice-state-updated
relationship-changed
channel-selected
channel-changed
guild-changed
member-changed
gateway

plugin-info

record

Static description of a plugin, returned by plugin.info.

Field	Type	Description
name	string	Unique name. ASCII letters, digits, - and _ only.
description	string
authors	list<string>
tags	list<string>	Categories shown in the plugin list, e.g. Chat, Privacy, Utility.
dependencies	list<string>	Names of plugins that must run before this one. They are started automatically.
enabled-by-default	bool
required	bool	Required plugins cannot be disabled.
settings	list<setting>
commands	list<command>
hooks	list<hook>
events	list<event-kind>

user

record

Field	Type	Description
id	snowflake
username	string
global-name	option<string>	Display name. none falls back to the username.
avatar	option<string>	Avatar hash.
bot	bool
system	bool
public-flags	u64

member

record

A user’s membership in a guild.

Field	Type	Description
guild-id	snowflake
user-id	snowflake
nick	option<string>	Guild nickname.
avatar	option<string>	Guild-specific avatar hash.
roles	list<snowflake>
joined-at	option<string>	ISO 8601 timestamp.
premium-since	option<string>	ISO 8601 timestamp of when the member started boosting.
communication-disabled-until	option<string>	ISO 8601 timestamp until which the member is timed out.
pending	bool	Has not passed membership screening yet.

role

record

Field	Type	Description
id	snowflake
name	string
color	u32	RGB color. 0 means no color.
hoist	bool	Shown separately in the member list.
position	s32
permissions	u64	Permission bitfield.
managed	bool	Managed by an integration.
mentionable	bool
icon	option<string>	Role icon hash.
unicode-emoji	option<string>

guild

record

Field	Type	Description
id	snowflake
name	string
icon	option<string>	Icon hash.
banner	option<string>	Banner hash.
owner-id	snowflake
description	option<string>
member-count	option<u64>
features	list<string>	Discord guild feature flags, e.g. COMMUNITY.
premium-tier	u8	Boost level, 0 to 3.

channel-kind

enum

Case	Description
guild-text
dm
guild-voice
group-dm
guild-category
guild-announcement
announcement-thread
public-thread
private-thread
guild-stage-voice
guild-directory
guild-forum
guild-media
unknown	A channel type this API version does not know.

overwrite-kind

enum

Case	Description
role
member

permission-overwrite

record

Per-channel permission change for a role or a member.

Field	Type	Description
id	snowflake	Role or user ID, depending on kind.
kind	overwrite-kind
allow	u64
deny	u64

channel

record

Field	Type	Description
id	snowflake
kind	channel-kind
guild-id	option<snowflake>	none for DMs and group DMs.
parent-id	option<snowflake>	Category of a guild channel, or parent channel of a thread.
name	option<string>	none for DMs.
topic	option<string>
position	s32
nsfw	bool
recipients	list<snowflake>	Users in a DM or group DM.
owner-id	option<snowflake>	Owner of a group DM or creator of a thread.
last-message-id	option<snowflake>
rate-limit-per-user	u32	Slowmode in seconds.
permission-overwrites	list<permission-overwrite>

attachment

record

Field	Type	Description
id	snowflake
filename	string
description	option<string>	Alt text.
content-type	option<string>	MIME type.
size	u64	Size in bytes.
url	string
proxy-url	string	URL served through Discord’s media proxy.
width	option<u32>	Image or video width in pixels.
height	option<u32>	Image or video height in pixels.

embed-field

record

Field	Type	Description
name	string
value	string
inline	bool

embed

record

A message embed, flattened to the fields plugins use.

Field	Type	Description
kind	option<string>	Embed type, e.g. rich, image, video, gifv, link.
title	option<string>
description	option<string>
url	option<string>
color	option<u32>	RGB color of the side bar.
timestamp	option<string>	ISO 8601 timestamp.
footer-text	option<string>
image-url	option<string>
thumbnail-url	option<string>
video-url	option<string>
provider-name	option<string>
author-name	option<string>
fields	list<embed-field>

emoji

record

A Unicode emoji (no id) or a custom emoji.

Field	Type	Description
id	option<snowflake>
name	string	The emoji itself for Unicode emoji, the name for custom emoji.
animated	bool

reaction

record

Field	Type	Description
emoji	emoji
count	u32
me	bool	The current user reacted with this emoji.

message

record

Field	Type	Description
id	snowflake
channel-id	snowflake
guild-id	option<snowflake>
author	user
content	string
timestamp	string	ISO 8601 timestamp.
edited-timestamp	option<string>	ISO 8601 timestamp of the last edit.
kind	u32	Discord message type, e.g. 0 default, 19 reply.
flags	u64	Discord message flags bitfield, e.g. 1 << 12 suppress notifications.
pinned	bool
tts	bool
mention-everyone	bool
mentions	list<snowflake>	Mentioned user IDs.
mention-roles	list<snowflake>	Mentioned role IDs.
attachments	list<attachment>
embeds	list<embed>
reactions	list<reaction>
sticker-ids	list<snowflake>
referenced-message-id	option<snowflake>	The message this one replies to or forwards.
nonce	option<string>	Client-generated ID used to match a sent message with its confirmation.
webhook-id	option<snowflake>

status

enum

Case	Description
online
idle
dnd
invisible
offline

activity

record

A game, stream, listening or custom status activity.

Field	Type	Description
name	string
kind	u8	Discord activity type: 0 playing, 1 streaming, 2 listening, 3 watching, 4 custom, 5 competing.
details	option<string>
state	option<string>
url	option<string>
application-id	option<snowflake>
created-at	option<u64>	Unix time in milliseconds.
start	option<u64>	Unix time in milliseconds.
end	option<u64>	Unix time in milliseconds.

presence

record

Field	Type	Description
user-id	snowflake
guild-id	option<snowflake>
status	status
activities	list<activity>
desktop	option<status>	Status per platform. none when the user is not connected from that platform.
mobile	option<status>
web	option<status>

voice-state

record

Field	Type	Description
user-id	snowflake
guild-id	option<snowflake>
channel-id	option<snowflake>	none once the user leaves voice.
self-mute	bool
self-deaf	bool
mute	bool	Server mute.
deaf	bool	Server deafen.
self-stream	bool	Streaming with Go Live.
self-video	bool
suppress	bool	Suppressed in a stage channel.

relationship-kind

enum

Case	Description
none
friend
blocked
incoming-request
outgoing-request
implicit

relationship

record

The current user’s relationship with another user.

Field	Type	Description
user-id	snowflake
kind	relationship-kind	none after the relationship was removed.
nickname	option<string>	Friend nickname.
since	option<string>	ISO 8601 timestamp.

message-ref

record

Field	Type	Description
channel-id	snowflake
message-id	snowflake
guild-id	option<snowflake>

deleted-message

record

Field	Type	Description
reference	message-ref
message	option<message>	The message as it was before deletion, if PhoenixCord had it cached.

message-update

record

Field	Type	Description
message	message
previous	option<message>	The message before the update, if PhoenixCord had it cached.

typing

record

Field	Type	Description
channel-id	snowflake
guild-id	option<snowflake>
user-id	snowflake

channel-selection

record

The guild and channel the user is looking at.

Field	Type	Description
guild-id	option<snowflake>	none for DMs and the home view.
channel-id	option<snowflake>

gateway-dispatch

record

A raw Discord gateway dispatch.

Field	Type	Description
name	string	Dispatch name, e.g. MESSAGE_CREATE.
data	string	The dispatch payload as JSON.

http-header

record

Field	Type	Description
name	string
value	string

http-request

record

Field	Type	Description
method	string	HTTP method, e.g. GET.
url	string
headers	list<http-header>
body	option<list<u8>>

http-response

record

Field	Type	Description
status	u16
headers	list<http-header>
body	list<u8>

discord-request

record

A request to Discord’s REST API, sent through the client with the user’s session.

Field	Type	Description
method	string	HTTP method, e.g. GET.
path	string	API path without the version prefix, e.g. /users/@me/invites.
body	option<string>	JSON body.

discord-response

record

Field	Type	Description
status	u16
body	string	JSON body.

command-value

variant

Case	Payload	Description
text	string
integer	s64
number	f64
boolean	bool
snowflake	snowflake	User, channel, role, mentionable and attachment options.

command-argument

record

Field	Type	Description
name	string
value	command-value

command-invocation

record

A slash command the user ran.

Field	Type	Description
command	string
channel-id	snowflake
guild-id	option<snowflake>
arguments	list<command-argument>

ui-action

record

The user interacted with an element the plugin rendered.

Field	Type	Description
action	string	The action string the plugin gave the element.
value	option<setting-value>	The new value of a toggle, text input or select.

event

variant

Delivered to plugin.on-event.

Case	Payload	Description
ready		The client connected and the initial state is loaded.
logout		The user logged out. All client state is cleared.
message-created	message
message-updated	message-update
message-deleted	deleted-message
typing-started	typing
presence-updated	presence
voice-state-updated	voice-state
relationship-changed	relationship
channel-selected	channel-selection
channel-changed	snowflake	A channel was created, updated or deleted.
guild-changed	snowflake	A guild was created, updated or deleted, or one of its roles changed.
member-changed	member
gateway	gateway-dispatch	Every gateway dispatch, raw. Prefer the typed events.
timer	u64	A timer from host.set-timeout or host.set-interval fired.
http	tuple<u64, result<http-response, string>>	Result of host.fetch.
discord	tuple<u64, result<discord-response, string>>	Result of actions.request-discord.
action	ui-action	The user interacted with an element, menu item or button from this plugin.
command	command-invocation	The user ran one of this plugin’s commands.
setting-changed	string	A setting of this plugin changed. Carries the setting key.

color-token

enum

A color from the client theme. Prefer tokens over rgb so plugin UI follows the theme.

Case	Description
text-normal
text-muted
text-link
text-positive
text-warning
text-danger
text-brand
background-primary
background-secondary
background-tertiary
background-floating
background-modifier-hover
interactive-normal
interactive-hover
interactive-active
interactive-muted
border-subtle
brand
status-online
status-idle
status-dnd
status-offline

color

variant

Case	Payload	Description
token	color-token
rgb	u32	0xRRGGBB.

direction

enum

Case	Description
row
column

align

enum

Case	Description
start
center
end
stretch

text-size

enum

Case	Description
xs
sm
md
lg
xl

text-weight

enum

Case	Description
normal
medium
semibold
bold

style

record

Layout and appearance of a node. Lengths are in logical pixels. none keeps the client default.

Field	Type	Description
direction	option<direction>	Direction children are laid out in. Stacks default to column.
align	option<align>	Cross-axis alignment of children.
justify	option<align>	Main-axis alignment of children.
gap	option<f32>
padding	option<f32>
width	option<f32>
height	option<f32>
grow	bool	Take up remaining space in the parent.
radius	option<f32>	Corner radius.
background	option<color>
foreground	option<color>	Text and icon color.
text-size	option<text-size>
text-weight	option<text-weight>

icon

variant

Case	Payload	Description
named	string	An icon from the client’s icon set, e.g. link, copy, settings.
svg	string	Inline SVG markup. currentColor follows the node’s foreground color.

button-variant

enum

Case	Description
primary
secondary
danger
link

button

record

Field	Type	Description
label	option<string>
icon	option<icon>
variant	button-variant
action	string	Sent back in event.action when clicked.
disabled	bool

toggle

record

Field	Type	Description
checked	bool
action	string	Sent back in event.action with the new boolean value.

text-input

record

Field	Type	Description
value	string
placeholder	option<string>
multiline	bool
action	string	Sent back in event.action with the new text value.

select

record

Field	Type	Description
options	list<select-option>
selected	option<string>	Value of the selected option.
action	string	Sent back in event.action with the selected text value.

image

record

Field	Type	Description
url	string
width	option<f32>
height	option<f32>

link

record

Field	Type	Description
text	string
url	string

node-kind

variant

Case	Payload	Description
stack		A container that lays out its children according to style.
text	string
icon	icon
image	image
button	button
toggle	toggle
text-input	text-input
select	select
link	link
code	string	Monospaced code block.
divider
spinner

node

record

One node of an element.

Field	Type	Description
kind	node-kind
style	style
tooltip	option<string>	Shown when hovering the node.
children	list<u32>	Indices of child nodes in element.nodes.

element

record

A tree of UI nodes rendered by the client. WIT has no recursive types, so the tree is flattened: nodes[0] is the root and children are referenced by index.

Field	Type	Description
nodes	list<node>

outgoing-message

record

A message about to be sent.

Field	Type	Description
channel-id	snowflake
content	string
reply-to	option<snowflake>	The message being replied to.
flags	u64	Message flags bitfield.
sticker-ids	list<snowflake>

outgoing-edit

record

An edit about to be saved.

Field	Type	Description
channel-id	snowflake
message-id	snowflake
content	string

send-decision

variant

What to do with an outgoing message or edit.

Case	Payload	Description
keep		Send it unchanged.
replace	string	Send it with this content instead. Later plugins see the replaced content.
cancel		Do not send it. No later plugin is called.

popover-button

record

A button in the message hover toolbar.

Field	Type	Description
label	string
icon	icon
action	string	Sent back in event.action when clicked.
danger	bool

chat-bar-context

record

Where a chat bar is rendered.

Field	Type	Description
channel-id	snowflake
main-chat	bool	The main channel chat, as opposed to a thread sidebar or forum composer.

chat-bar-button

record

A button next to the message input.

Field	Type	Description
tooltip	string
icon	icon
action	string	Sent back in event.action when clicked.
active	bool	Draw the button highlighted.

user-target

record

Field	Type	Description
user-id	snowflake
guild-id	option<snowflake>	The guild the menu was opened in.
channel-id	option<snowflake>	The channel the menu was opened in.

role-target

record

Field	Type	Description
guild-id	snowflake
role-id	snowflake

image-target

record

Field	Type	Description
url	string
channel-id	option<snowflake>
message-id	option<snowflake>

menu-target

variant

What a context menu was opened on.

Case	Payload	Description
user	user-target
message	message-ref
channel	snowflake	A channel ID.
guild	snowflake	A guild ID.
role	role-target
image	image-target
link	string	A link URL.
composer	snowflake	The message input of a channel.

menu-item

record

A context menu item. Items form a tree through parent.

Field	Type	Description
label	string
action	string	Sent back in event.action when clicked.
icon	option<icon>
checked	option<bool>	Shows a checkbox in this state. none for plain items.
danger	bool	Draw the item in the danger color.
parent	option<u32>	Index of the parent item in the returned list. Items with children open a submenu.

profile-context

record

Field	Type	Description
user-id	snowflake
guild-id	option<snowflake>	The guild the profile is shown for.
channel-id	option<snowflake>	The channel the profile was opened from.

badge

record

A badge shown on a user profile.

Field	Type	Description
tooltip	string
icon	icon
action	option<string>	Sent back in event.action when clicked. none makes the badge static.

member-context

record

A member list or DM list row.

Field	Type	Description
user-id	snowflake
guild-id	option<snowflake>
channel-id	option<snowflake>

toast-kind

enum

Case	Description
message
success
failure

notice

record

A bar shown at the top of the client.

Field	Type	Description
message	string
button	option<string>	Button label.
action	option<string>	Sent back in event.action when the button is clicked.

notification

record

A desktop notification.

Field	Type	Description
title	string
body	string
icon	option<string>	Image URL.
action	option<string>	Sent back in event.action when the notification is clicked.

navigation

variant

Somewhere the client can navigate to.

Case	Payload	Description
channel	channel-selection
message	message-ref	Jump to a message.
user-profile	profile-context	Open a user profile.
guild	snowflake
settings	string	Open a settings section by name.