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}]}]}]}
typeComponentFields
1action rowcomponents: up to 5 buttons, or exactly one select
2buttonstyle 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
3string selectcustom_id, options (1 to 25: label, value, description, default), placeholder (up to 150), min_values, max_values, disabled
5user selectmembers (not bots); custom_id, placeholder, min_values, max_values, disabled
6role selectroles (not @everyone, not the managed bot roles); same fields
8channel selecttext, voice and forum channels; same fields
  • A custom_id is 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 with 50035, 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"}]}]}}
  • title up to 45 characters; 1 to 5 rows of one text input (type 4) each.
  • Text input: custom_id, label (up to 45), style 1 short or 2 paragraph, min_length and max_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.

Something wrong on this page? Tell us.