Slash commands, buttons and modals on Yappio

Registering a command

A command has a name, a short description and optional options such as a text, a number or a choice. When someone types a slash in a message box, Yappio lists the commands available in that server, with their descriptions, so a good description is part of your bot's user interface.

Options can offer autocomplete: while the person types, Yappio asks your endpoint for suggestions and shows them. Autocomplete requests are signed like every other interaction.

Replying

A reply can contain text and, optionally, buttons or a modal.

• text: the message people read.
• components: buttons in action rows, each with an id and a label.
• modal: a form of up to five inputs.
• ephemeral: a reply only the person who ran the command can see.

Handling a button press

Each button has an id. When someone presses it, Yappio sends your endpoint a signed request carrying that id and the user who pressed it. You answer by replying or by updating the original message.

Keep ids short and stable. They are how your handler knows which button was pressed, and they should not contain secrets.

Timing and followups

You have three seconds to send the first response. If the real work takes longer, acknowledge first and send followups afterwards; the interaction token stays valid for 15 minutes.

Designing a command people remember

A command is something a person types, so its name should be short and obvious. Prefer one clear verb over a clever word, keep options to a minimum, and give every option a description so the app can show it as the person types. If you need many options, a form is usually the better tool.

A command should also answer quickly. Your app has three seconds to respond to an interaction. If the work takes longer than a moment, reply with a short acknowledgement first and send a followup when you have the result, so the person is not left staring at nothing. The token that comes with an interaction is valid for 15 minutes.

Buttons and state

A button press arrives as its own interaction and needs to be matched to something. Keep the information that identifies what the button is for inside the button itself, rather than in memory that may be lost if your bot restarts. That way a button on an old message still does the right thing.

Remember too that a message with buttons can be seen by many people. Decide whether each press should be for the person who pressed it, or for the whole room, and say so in the text. An ephemeral reply is visible only to the person who pressed. The SDK samples are sketches of an interface that is coming soon, and the details may change.

Good habits

Prefer a button over asking someone to type a magic word. Make destructive actions require a second press. Describe what a command does in plain language, not in the vocabulary of your own code.