sometimescommands and interactions
commands are available to their installing user in eligible chats. they do not expose ambient conversation history.
command definitions
each application can publish up to 100 commands. name is 1–32 lowercase ASCII letters, digits, hyphens or underscores, description is 1–100 visible characters. each command has up to 25 named options of type string, integer, number, boolean, user, message or attachment, with required flags and optional choices. choices are limited to 25. strings are at most 4,000 characters. no arbitrary HTML, scripts, forms or executable components. the command picker shows bot identity to disambiguate names.
using commands in chat
type / as the first character in the message bar to open the command picker. use the arrow keys and Tab to complete a command, then fill its named options. Escape closes the picker. the invocation and its arguments remain private to the person submitting it; a bot’s public replies appear in the shared chat. a single-chat installation takes precedence over the same user’s account-wide installation, including when commands were declined for that chat.
invocation routing
only the installing user can invoke that installation’s commands. a different member needs their own installation; another user’s click never borrows the installer’s authority. include installer_id, installation_id, application_id, chat_id, command_id, configuration_revision and validated options in Interaction. user/message/attachment options contain IDs and basic labels only unless their normal read/download grants permit more. command input itself is explicit user-submitted data and needs no ambient message-read grant. the server verifies command existence and scope against the installation’s pinned revision.
acknowledgement and replies
acknowledge within three seconds with ephemeral:true or false. a missed deadline expires the interaction and shows a user-facing failure. after ACK, one initial response and up to four follow-ups are allowed for 15 minutes from creation; the visibility choice is fixed. public responses need bot.messages.send, private responses need bot.messages.ephemeral, in addition to commands. all responses use bot identity. other actions, including delegated sends, still require their own grants. error messages sent by the platform are not a grant to send arbitrary content.
command routes
command definition routes are application-level and update the draft; commands must be enabled in the draft configuration. response routes require the interaction’s exact installation header and still-active grants. only responses associated with that interaction can be edited or deleted through its response routes.
scroll the table horizontally to see all columns.
| method and path | request | result |
|---|---|---|
| GET /applications/@me/commands | cursor, limit | draft Command list |
| POST /applications/@me/commands | name, description, options[] | 201 Command{id,revision,...} |
| PATCH /applications/@me/commands/{id} | definition patch; If-Match | Command |
| DELETE /applications/@me/commands/{id} | If-Match | 204; remove from draft |
| POST /interactions/{id}/ack | ephemeral: boolean | 204; fixed response visibility |
| POST /interactions/{id}/responses | content, ephemeral | 201 Message; initial then follow-ups |
| PATCH /interactions/{id}/responses/{message} | content; If-Match | MessageReceipt with changed content and revision; bot.messages.edit required |
| DELETE /interactions/{id}/responses/{message} | If-Match | 204; bot.messages.delete required |
interaction payload
an interaction is not a user session or bearer credential. the application token, installation and live permission checks remain necessary.
{
"id": "interaction_example",
"application_id": "app_example",
"installation_id": "install_example",
"installer_id": "user_example",
"chat_id": "chat_example",
"command_id": "command_hello",
"configuration_revision": "3",
"options": {},
"created_at": "2026-10-20T07:00:00Z",
"ack_deadline": "2026-10-20T07:00:03Z",
"expires_at": "2026-10-20T07:15:00Z"
}