Build a Hexis bot
A bot is an account that a program drives. It sits in servers, answers what members send it, and posts messages. You write the program in Python, Node or Rust; the same runtime underneath handles the encryption, the reconnects and the storage.
What a bot is
- An app plus a bot account. You create an app in your Hexis account. Creating it also makes a bot user for it (
bot_<id>) and a bot token that starts withhxb_. - A program you run. The bot lives on your machine or your server, not ours. It keeps a state directory with its own device keys and an encrypted cache. Lose that directory and the bot becomes a new device.
- A member with a role. When someone installs it in a server, it gets a managed role named after the bot, with the permission bits the installer chose. Nobody can hand that role to a person.
- Three ways in. A Rust runtime (
hexis-bot), a Python SDK and a Node SDK. The SDKs are thin layers over the Rust runtime. Encryption is never rewritten in Python or JavaScript.
Two kinds of bot
A server is end-to-end encrypted only if its owner chose that when creating it (public is the default, and the choice cannot be changed later). In an encrypted server a bot cannot just read the channel. The person installing it picks one of two kinds, and the install sheet says what it means.
| Reader | No-read | |
|---|---|---|
| What it sees | Every message in the channels its role can see. It is a full encrypted member of the server. | Only what members send it directly: slash commands, mentions of it, and button clicks. Messages in channels reach it without their text. |
| Keys | Holds the server’s channel keys. Those keys cover the whole server, so the server’s permission checks, not the keys, decide which channels it receives. | Never gets a channel key. Members’ apps do not give it one. |
| What it can do | Read, post, react, moderate (within its role). | Post, react, moderate (within its role), and answer the things sent to it. |
| Counts toward the encrypted-member cap | Yes | No |
| Pick it when | The bot has to read the chat: moderation, search, summaries. | The bot only answers commands. This is the safe default. |
The member-side parts of commands, mentions and buttons are not shipped yet arriving (#1436 to #1438). The sealed channel they use is shipped, and the command-line client’s /bot interact drives it today.
On a server that is not end-to-end encrypted there are no keys to hold back. The bot sees what its role can see, and the privileged message_content intent covers message text arriving.
The no-read choice is permanent for that bot account in that server. To read there, create a new app (a new bot account) and install it as a reader. See Concepts for how this is enforced.
Private and public bots
- Private bots need no review. Anyone can create a bot and add it to servers where they have Manage Server. A private app can be installed in up to 25 servers.
- Public bots are reviewed. A public “Add to server” link or a directory listing needs operator approval arriving. The reviewer sees the kind, the privileged intents, the permissions and the privacy text. Editing any of those afterwards drops the approval.
One bot per process
A process runs one bot, and one process uses one state directory. A second bot in the same process is refused, and two processes sharing a directory corrupt each other. To run several bots, run several processes with a directory each.
The token
- Shown once. Creating the app returns
bot_tokenandbot_user_idin that one response. Hexis stores only a hash of the token, so it cannot show it again. - Header only. The token goes in the
x-api-keyheader of the bot’s socket. Never put it in a query string or in the endpoint URL; the runtime refuses an endpoint containingtoken=. - Reset needs step-up. Replacing the token asks for a fresh second factor, and it closes every live socket on the old token. The new token is shown once.
- It dies with the app. Revoking the app ends the token for good, and so does an operator kill (see Safety; a kill can be undone by an operator, after which you reset the token). Suspending the owner’s account only refuses the token while the suspension lasts; it works again afterwards.
- Keep it out of logs. The runtime never prints it, and its config errors name a line and column instead of quoting the file.
Other credentials keep their old meaning: hxo_ OAuth tokens act on a person’s grant and cannot join servers, and hxk_ API keys are for your own account. Only hxb_ opens a bot socket.
Where to go next
- Quickstart: from nothing to a running echo bot.
- Concepts: install, encryption, interactions, events, notices, safety.
- Reference: events, actions, errors, config, routes.
- Limits: every cap in one table.
Things that are not shipped yet are marked arriving. Treat those as plans, not promises.