Message Components

Components put things people can use on your bot's messages: buttons, select menus, and with the IS_COMPONENTS_V2 flag a whole message laid out from containers, sections, text, images and separators. Bots can also open modals, small forms with text inputs.

The shapes, type numbers and field names are Discord's, so existing component builders work. Field names are snake_case (custom_id, min_values); camelCase (customId) is accepted too. Messages come back with components normalized: numeric type and style, and defaults filled in.

#Who can send them

Clicks go to the bot that sent the message. Published copies of announcements keep their components with buttons and select menus switched off.

#Two ways to build a message

Classic ("v1"). components holds up to 5 action rows shown under the message's text and embeds. Each row holds 1-5 buttons or exactly one select menu.

{
	"content": "Ready for the raid?",
	"components": [
		{
			"type": 1,
			"components": [
				{ "type": 2, "style": 3, "label": "I'm in", "custom_id": "raid:join" },
				{ "type": 2, "style": 2, "label": "Maybe", "custom_id": "raid:maybe", "emoji": { "name": "🤔" } },
				{ "type": 2, "style": 5, "label": "Raid guide", "url": "https://example.com/guide" }
			]
		}
	]
}

Components only ("v2"). Set "flags": 32768 (IS_COMPONENTS_V2, 1 << 15) and the whole message is built from components: no content, no embeds, no files or polls. Text goes in text displays. A message sent with the flag keeps it: edits can't remove it (invalid_flags), and an edit can turn a classic message into v2 if its text and embeds are gone.

{
	"flags": 32768,
	"components": [
		{
			"type": 17,
			"accent_color": 3065014,
			"components": [
				{ "type": 10, "content": "**Patch 1.4** is out, <@103600000000000000>!" },
				{
					"type": 9,
					"components": [
						{ "type": 10, "content": "**New map: Harbor**" },
						{ "type": 10, "content": "Night fights, fog and a lighthouse." }
					],
					"accessory": { "type": 11, "media": { "url": "https://example.com/harbor.png" }, "description": "Harbor at night" }
				},
				{ "type": 14, "divider": true, "spacing": 1 },
				{ "type": 12, "items": [{ "media": { "url": "https://example.com/1.png" } }, { "media": { "url": "https://example.com/2.png" }, "spoiler": true }] },
				{ "type": 1, "components": [{ "type": 2, "style": 1, "label": "Send feedback", "custom_id": "feedback" }] }
			]
		}
	]
}

#Component types

File components (13) and premium buttons (style 6) aren't supported yet. Every component may have an optional numeric id, unique within the message.

#Buttons

#Select menus

User selects list the server's members (in a DM, the two of you), role selects its roles, channel selects the channels the person can see.

#Layout (v2)

Media URLs must be http(s) (no attachment:// yet).

#Limits

Anything wrong answers 400 invalid_components naming the spot, for example components[0].components[2].label can be up to 80 characters. A v2 message with text or embeds gets invalid_components too; unknown flags get invalid_flags.

Text displays count as the message's text: their mentions ping, and a dev://experiment link in one makes the message experiment-only, like in content. A reply to a v2 message previews its first text display.

#Clicks and choices

Anyone who can see the message may click a button or pick in a select menu, as often as they like (a rate limit applies). Switched-off components refuse clicks (component_disabled). Your bot gets an interaction with "type": "component":

{
	"type": "component",
	"id": "103745871234569999",
	"token": "9c2d...",
	"applicationId": "103712345678901247",
	"channelId": "103700000000000001",
	"serverId": "103700000000000000",
	"user": { "id": "103600000000000000", "username": "andre", "displayName": "Andre", "avatarUrl": null, "roles": [] },
	"message": { "id": "103745871234568500", "content": "Ready for the raid?", "components": [], "flags": 0, "interactionName": "" },
	"data": { "customId": "raid:join", "componentType": 2, "label": "I'm in" }
}

message is the full message object the component is on (interactionName = the command it answered, or ""). For select menus, data has values (the option values, or ids) and, for user, role, mentionable and channel selects, resolved:

"data": {
	"customId": "pick-mod",
	"componentType": 5,
	"values": ["103600000000000007"],
	"resolved": {
		"users": { "103600000000000007": { "id": "103600000000000007", "username": "mira", "displayName": "Mira", "avatarUrl": null } }
	}
}

resolved can also hold roles ({ id, name, color }) and channels ({ id, name, type, parentId }). Values are checked first: options that don't exist, people not in the server, channels the person can't see or of the wrong type, and too few or too many values are refused before your bot hears about them.

#Answering clicks

Answer within 3 seconds like any interaction (callback). Besides message and defer, clicks take:

// A counter: each click updates the same message.
if (i.type === 'component' && i.data.customId.startsWith('count:')) {
	const n = Number(i.data.customId.split(':')[1]) + 1;
	await post(`/interactions/${i.id}/${i.token}/callback`, {
		type: 'update',
		components: [{ type: 1, components: [{ type: 2, style: 1, label: `Clicked ${n} times`, custom_id: `count:${n}` }] }]
	});
}

If your bot doesn't answer in time, the person sees that it didn't respond. Ephemeral answers with components can be clicked (and updated) by the person they were shown to for 15 minutes.

Bots that sent a plain list of buttons (without an action row, with "type": "button") keep working: such a list is put into rows of 5.

#Modals

Answer a command or a click with modal to open a form (not a modal submit: one form per interaction):

{
	"type": "modal",
	"title": "Send feedback",
	"custom_id": "feedback",
	"components": [
		{ "type": 1, "components": [{ "type": 4, "custom_id": "topic", "label": "Topic", "style": 1, "max_length": 60 }] },
		{ "type": 1, "components": [{ "type": 4, "custom_id": "details", "label": "Details", "style": 2, "min_length": 10, "max_length": 500, "required": false }] }
	]
}

When the person sends it, required fields and lengths are checked, then your bot gets "type": "modal_submit" (with message too when the form was opened from a click):

{
	"type": "modal_submit",
	"id": "103745871234570001",
	"token": "1f0a...",
	"data": {
		"customId": "feedback",
		"fields": [
			{ "customId": "topic", "value": "Buttons" },
			{ "customId": "details", "value": "They work nicely." }
		]
	}
}

Answer it like a command (message, defer, and update / deferUpdate when it came from a click). Each form can be sent once; closing it sends nothing.