Introduction

A wisp is a member of a Woosh server that is not a person: a program you write and run, which a server’s admin adds. People type its commands after a /, press the buttons on its cards, and read its lines. It hears what happens in the server and acts on it, within exactly what the admin approved.

Woosh’s own wisps will be built from these pages alone, as yours are. There is no private door: whatever ours need, you get. If something is missing here, it is missing for us too, and we fix it here.

How it fits together

your wisp ──── one WebSocket, the line ────▶ Woosh
          ◀─── events it hears ─────────────
          ──── HTTP, for its token and pictures ──▶

• The line carries everything: the events your wisp hears come in on it, and every action it takes (a line posted, a card edited, a role given) is a call on it. So is every read: a channel’s history, a server’s members, who pressed a tally. One protocol, the one the Woosh apps speak. See The line.
• HTTP is for two things only: buying a token, and uploading the pictures on your wisp’s cards. Your wisp’s token reaches no other route. You make and look after the wisp itself over HTTP as well, signed in as yourself (Quick start).
• Your token says only which wisp you are. What your wisp may do in each server is kept by Woosh for that server, and checked at every event and every call.

What a wisp can do

• Hear a server’s shape, its members and its lines, each only if the admin granted it (What a wisp hears).
• Read a channel’s recent lines and the server’s members, where it hears them (Catching up).
• Offer commands, and answer each run once, in the channel or privately to the person who ran it (Commands).
• Post lines with cards: text, fields, grids, pictures, progress, buttons and menus (Cards), and move them on as people press them (Presses and private cards).
• React, edit its own lines, delete its own lines (or anyone’s, with manage messages), give and take roles, kick and ban, with the server permissions an admin gave it (Acting in a server).

What a wisp cannot do

• Speak, play or record in voice.
• Start a DM with a person, or act in one.
• Hear presence, typing, read marks, anyone’s inbox, or DMs between people.
• Run on Woosh’s machines, or draw web pages inside the apps.
• Act in a server it is not in.

And never, under any grant:

• See a line before it is posted. A wisp is never in the path of someone’s message.
• Open a window, a page or a link for a person who did not press for it.
• Show pictures from outside addresses. Every picture on a card is a file the wisp uploaded to Woosh, so no outside host learns who looked.
• Show each viewer of a shared card something different. A private answer (an aside) is the way to tell one person something.
• Post under another name or picture per line.
• Put anything on a card that the person looking cannot see, or play sounds.

How a server lets it in

A wisp asks to hear and to do, and marks the items it cannot work without as required:

Part	Items
What it hears	shape (channels, roles, emoji, layout, and the server itself), members (joins, leaves, role changes), messages (every line, edit, deletion and reaction), voice (can be granted; hears nothing yet)
What it does	post (post and edit lines, and answer in the channel), react, commands (offer commands and hear them run); and server permissions: manage messages, manage roles, kick, ban and the rest, never Administrator (Permissions)

An Administrator of the server adds it, approving what it asks for: they can leave out any item it does not require, and choose where it works, every channel or only the ones they pick. What they approve is the wisp’s grant in that server. Before adding a wisp, anyone signed in can read what it asks for with GET /api/wisps/{id}: its name, picture, description and maker, how many servers it is in, whether Woosh has reviewed it, and every item. The approval page in the apps is not open yet; today an admin adds a wisp with one request, as the quick start shows.

• Where it works covers lines. A wisp given only #general hears no lines from other channels, posts nowhere else, and its commands are offered only there. A server’s shape and its members belong to the whole server, and so do kicks, bans and roles.
• Never upward by itself. A wisp that comes to ask for more keeps the grant it has in every server until an admin there approves the rest, which they see as asksMore. A wisp that asks for less loses the rest at once, in every server.
• Admins stay in charge. They can leave out any item the wisp does not require, change where, or remove the wisp at any time. Your wisp hears each change as a server event with its new grants, and its removal as server.gone.
• Roles. The permissions sit on a role made for the wisp and named after it, so every check a person meets holds for it too. A wisp never touches a role at or above its own highest, and never kicks or bans anyone whose highest role is. An admin moves the wisp’s role among the server’s roles like any other.
• Review. A wisp that asks to read messages can be in up to 100 servers until Woosh has reviewed it; past that, it cannot be added to more. A wisp that does not ask to read messages is never held to this.

Presence

A wisp is online while one of its lines is up, and offline after the same short grace a person gets. Woosh keeps its presence while the line is open, so a wisp sends none. It can set words of its own with the activity call, though the apps do not draw them yet (Your wisp’s words).

Names

A wisp’s name is a username, from the same pool as people’s: 2 to 32 letters, digits, _, - or ., and taken whatever the casing: Lucky is not free once lucky is. No wisp carries a person’s name, nor a person a wisp’s. The apps draw a Wisp mark beside its name on its lines and in the member list. Its picture is one of Woosh’s own, given when it is made.

Ready? The quick start gets a wisp answering its first command.