Buttons, select menus and modals
A bot message can carry buttons and select menus, and a command or a click can open a small form. Every click is a new interaction for your bot.
Components
Components go into components of POST /channels/{id}/messages, of an interaction response (callback types 4 and 7, follow-ups, @original) and of PATCH /channels/{id}/messages/{id}. Only bots can set them, on their own messages.
{"content": "Deploy v2.4 to production?",
"components": [{"type": 1, "components": [
{"type": 2, "style": 3, "label": "Deploy", "custom_id": "deploy:v2.4"},
{"type": 2, "style": 2, "label": "Cancel", "custom_id": "cancel"},
{"type": 2, "style": 5, "label": "Changelog", "url": "https://example.org/changes"}]},
{"type": 1, "components": [
{"type": 3, "custom_id": "env", "placeholder": "Environment",
"options": [{"label": "Staging", "value": "staging"}, {"label": "Production", "value": "prod", "default": true}]}]}]}
| type | Component | Fields |
|---|---|---|
1 | action row | components: up to 5 buttons, or exactly one select |
2 | button | style 1 primary, 2 secondary, 3 success, 4 danger (each with custom_id) or 5 link (with url); label (up to 80) and/or emoji; disabled |
3 | string select | custom_id, options (1 to 25: label, value, description, default), placeholder (up to 150), min_values, max_values, disabled |
5 | user select | members (not bots); custom_id, placeholder, min_values, max_values, disabled |
6 | role select | roles (not @everyone, not the managed bot roles); same fields |
8 | channel select | text, voice and forum channels; same fields |
- A
custom_idis 1 to 100 characters, unique within the message. It is your own state ("deploy:v2.4") and comes back exactly with every click. - At most 5 rows and 25 components. A message may consist of components only.
- Mentionable selects (type
7) and layout components are not offered; a message that contains them is refused with50035, so you learn at once.
Clicks
Any member who can view the channel can use the components, also in a read-only channel, unless they are timed out. The server checks that the component still exists and is enabled, that select values are valid and visible to the member, and then delivers a new interaction to your bot:
{"op": 0, "t": "INTERACTION_CREATE", "s": 12, "d": {
"id": "...", "token": "...", "type": 3, "channel_id": "...", "application_id": "<bot id>",
"message": {"id": "...", "content": "Deploy v2.4 to production?", "components": [...]},
"data": {"custom_id": "env", "component_type": 3, "values": ["prod"]},
"member": {"user": {"id": "...", "username": "max", "display_name": "Max", "avatar_url": "/api/media/..."}}}}
User, role and channel selects add data.resolved with what was picked. Clicks and modal submits are limited to 30 a minute per member.
Ephemeral notes (responses with flag 64) can carry components too. They are not stored, so their components work for the 15 minutes the interaction lives, and only for the member who sees the note.
Modals
A modal is a small form, opened as the response to a command or a click (not to a modal submit), with callback type 9:
{"type": 9, "data": {"custom_id": "feedback", "title": "Feedback",
"components": [
{"type": 1, "components": [{"type": 4, "custom_id": "subject", "label": "Subject", "style": 1, "max_length": 80}]},
{"type": 1, "components": [{"type": 4, "custom_id": "body", "label": "What happened?", "style": 2, "required": false, "placeholder": "Tell us more"}]}]}}
titleup to 45 characters; 1 to 5 rows of one text input (type4) each.- Text input:
custom_id,label(up to 45),style1short or2paragraph,min_lengthandmax_length(up to 4000),required(default true),value(prefilled),placeholder(up to 100).
The submit reaches your bot as INTERACTION_CREATE type 5:
{"type": 5, "data": {"custom_id": "feedback", "components": [
{"type": 1, "components": [{"type": 4, "custom_id": "subject", "value": "Login"}]},
{"type": 1, "components": [{"type": 4, "custom_id": "body", "value": ""}]}]}}
A modal can be submitted once, by the member it was opened for, within 15 minutes. Closing it sends nothing to the bot.
With an SDK
import { actionRow, button, ButtonStyle, modal, textInput } from '@mnema-xyz/bot-sdk'
await bot.rest.createMessage(channelId, {
content: 'Ready?',
components: [actionRow(button({ customId: 'go', label: 'Go', style: ButtonStyle.Success }))],
})
The builders return plain JSON, and plain objects work wherever builders do. The full examples with buttons and a modal are in each SDK: TypeScript, Go.