What is a bot? A guide for Yappio developers

A bot is a member with a job

On Yappio a bot appears in a server like a member, with a name and an avatar, and it is clearly marked as a bot. It does not log in with a person's account. Server owners decide whether to add it and what it may do.

How a bot connects

The flow has four parts:

• You create an app in the Developer Portal at https://yappio.chat/developers/applications and give it a bot account.
• A server owner installs the app through an OAuth2 install link and approves the permissions.
• When someone uses a command or presses a button, Yappio sends your endpoint a signed HTTP request.
• Your endpoint verifies the Ed25519 signature, then answers within three seconds.

What a bot can do

Within the permissions a server owner grants, a bot can reply to commands, post messages, attach buttons, open modals and react to events. It cannot read channels it has not been added to, and it cannot act outside the permissions of its role.

A bot that only responds to slash commands needs far fewer permissions than one that watches every message, and the guide recommends starting small.

What a bot should not do

Bots should say that they are bots, should not collect personal data they do not need, and should not send unsolicited messages. Keep your bot token private and replace it if it leaks.

Thinking about trust

A bot acts inside a community on behalf of whoever installed it, so the first question is what it should be allowed to do. A bot is added to a server through an OAuth2 install, where the person installing it sees what it asks for, and a bot should ask for the narrow set of permissions it needs. A bot that only posts a reminder has no reason to read every message.

Members should also be able to tell what a bot does. Say so in its description. A tool that pretends to be a person is a bad neighbour.

A first idea to try

A good first bot is small and boring: one command, one reply. Something that answers a question your community asks again and again, such as when the next meeting is or where the rules are, is a good choice. It teaches the basic loop of receiving a command, deciding what to say and replying, and it is easy to check.

Once that works, add a button, then a form. The next guides in this section cover them in that order. The SDKs that make this shorter are coming soon, and the samples that use them are sketches of their interface.

Naming and describing a bot

Give the bot a short name that says what it does and a one-line description that a member can read at a glance. Say what it can see, what it can do and who made it. A bot called kettle that posts the weekly plan is easier to understand than one called helper, and members who understand a bot are less likely to be uneasy about it. Include a contact address in the description so people know where to report a fault.

Where to go next

The next guide covers slash commands and buttons, and the one after that covers the local simulator, which is coming soon. The SDKs for Python and TypeScript are also coming soon; code on these pages that uses them is a sketch of the SDK interface.